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PREFRCE 


This description of the DCAM (Data Communication Access Method) program 
interfaces is intended for various user groups: 


- Q0 and M specialists and application engineers who vant a guide to the 
scope and capabilities of the interface, 


- programmers (ASSEMBLER, COBOL) wanting to acquire a basic knowledge of 
the subject in order to understand and use the more detailed information 
contained in the programming manuals, 


- system and network administrators who do not need to be experts on the 
interface but would Like to have a general knowledge of DCAM. 


ALL readers should be familiar with both the theory and practical 
application of BS2000. The use of DCAM also presupposes a knowledge of 
either ASSEMBLER or COBOL. 


The manual is divided into four parts: 
1. Position of DCAM in BS2000, range of functions and supported hardware. 


2. Explanation of basic concepts and points for consideration when 
planning programs or program systems. 


3. Description of the functions of all the DCAM calls and notifications 
relating to the existence of the DCAM appLication: virtual connection, 
data transmission. 


4. Outline of the coding of DCAM programs in ASSEMBLER and COBOL, and 
of the execution of such programs. 


Chapters 1 and 2 comprise a general introduction, an overview and 
information on program planning and organization. Because of the detailed 
functional descriptions, chapter 3 will be of- interest to all users 
requiring detailed information. Chapter 4 is intended in particular for 
application engineers; programmers will find it useful as an introduction 
to the relevant Programmer's Guide. The Layout of chapter 3 is identical to 
that of the same chapters in the User's Guides for ASSEMBLER and COBOL; 
this is intended to aid the programmer who wishes to refer to the 
functional descriptions. 


Since a Large number of new concepts have been introduced, a glossary of 
TRANSDATA terms has been included at the end of the manual. 


The present manual is part of the overall description of the Data 
Communication Access Method. Related Literature includes informative 
brochures on computer networks and teleprocessing with BS2000, and an 
outLine description of TRANSDATA DCM, as well as the "DCAM Macros" and 
"DCAM COBOL Calls" User's Guides. Separate manuals are available on 
generation and administration, and the programming of communication 
computers and terminals. 
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The changes made since the previous manual are given in List of 
Amendments 1. 


Other publications are referred to in the text by their "short titles"; 
the full titles are Listed in the bibliography. 


To help us continue to improve our manuals, please send us your comments, 
requests and suggestions using the pink reply forms provided. 


EditoriaL Department D ST PM 2 
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LIST OF RMENDMENTS 1 


The foLLowing amendments have been made since pubLication of the 
Revision October 1982 (DCAM V7.0) 

and incorporated in the 
Edition January 1985 (DCAM V8.0): 


Page Amendment 
meer ccce e mem eee n i d as UTC SA MMC ENS ONDE a 
27215, 3*3, 3-20 (Fig. 310) 
The application can also send a connection message to the 
partner when a connection is accepted. 


2712, 3-16, 3-29 
A GO signal may be issued (SIGNAL) following the ayer Loading 
of a connection. 


3-16 Specification of the maximum Length of the data to be 
transmitted (MAXLN) for optimum system buffer utilization. 


3-3, 3-5 
To use certain new functions in this version the user must 
specify DCAMVER when opening a DCAM application. 


3-17 (Fig. 3-8) 
New message editing options: EXTEND, NLOGC, LACK 


2-10, 2-12, 3-3, 3-5, 3-6, 3-32, 3-36 


The restriction on the processing of asynchronous 
notifications under COBOL no Longer applies. 
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1 DCAM IN THE TRANSDATA DATA COMMUNICATION SYSTEM 
GENERAL INTRODUCTION» 


Within the TRANSDATA data communication system, access methods such as DCAM 
are Located at the interface to the "outside", i.e. to the user. DCAM 
provides the user with all the capabilities of TRANSDATA at his program 
interface. At the same time, DCAM is integrated in the TRANSDATA DCM (Data 
Communication Methods) communication access system along with all other 
BS2000 access methods. s 


1.1 TRANSDATA DCH «DATA COMMUNICATION METHODS» 


In BS2000 Version 4, access to the data communication system has been 
impLemented by a standard system component. As is the case with the 
TRANSDATA components, this component has a multi-Level structure. This 
results in clear-cut interfaces, thus ensuring that subsequent 
modifications in the hardware configuration or the system software will not 
affect the user interface. The user will therefore not be faced with extra 
costs of reorganization when future developments offering further 
advantages become avaiLabLe. At present, TRANSDATA DCM provides the user 
with the following features: 


e Use of DCAM for handling transaction processing; 


e support of terminal programming through the application of virtual 
terminals; 


e administration at optional operator consoles, also, if desired, in a 
DCAM program using the muLticonsoLe operation module (UCON); 


e powerful support of the established interfaces for timesharing (RTIO) 
and remote batch processing (RBP). 


This high Level of convenience offered by the user interface is made 
possible by the modules provided in TRANSDATA for the user services: 


e DCAM (Data Communication Access Method) for the implementation of the 
DCAM interface in ASSEMBLER and COBOL; 


e VTSU (Virtual Terminal Support) for the implementation of the virtual 
terminals; 


e TIAM (Terminal Interactive Access Method) for the implementation of 
the RTIO ASSEMBLER interface (remote terminal input output); 


e RBAM (Remote Batch Access Method) for batch mode support with RBP 
(remote batch processing) commands. 


These modules, in turn, have a defined interface to BCAM (Basic 
Communication Access Method). The tasks common to all access methods, such 
as transport management, buffering, operation of the channel trunk to the 
front-end processor, etc. are implemented in this basic module. 


U1786-J-275-1-7600 i" 


Fig. 1-1 contains an overview of the TRANSDATA DCM components. 


The DCAM opens up the wide-ranging potential of the data communication 
system, especially unrestricted data communication with all 
communication partners (applications and terminals), to the user. 


TRANSDATA DCM 
(Data Communication Methods) 


. |nterface to another Interface to 968x Interface to 
host computer Front-end locally-connected 
via data exchange Processor terminals via 8170 
control Local Cluster Controller 


Fig. 1-1 Structure of TRANSDATA DCM 
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1.2 TRAFFIC RELATIONS IN THE DATA COMMUNICATION SYSTEM WITH DCRM. 


DCAM enabLes one or more tasks (programs) in the host computer to 
communicate with a single terminal or with a number of terminals. This 
would represent the classic traffic pattern known from the conventional 
star-type network where the processing capacity is concentrated in a single 
computer. However, DCAM also supports the principle of distributed 
processing power by means of computer-to-computer communication. The tasks 
(programs) of one computer can communicate vith the tasks (programs) of 
another computer. Moreover, tasks (programs) in the same host computer can 
also communicate with each other via DCAM. This is especially important for 
the test phase of such programs, as terminals can be easily simulated by 
programs. The traffic relations are shown in Fig. 1-2. 


Access to the "$CONSOLE" system application is also possible within the 
C user computer, thus enabLing program-based operation and administration of 

the system. If the appropriate commands are issued to the program from 

a terminal, the program can pass them on to "S$CONSOLE" (application for 

muLticonsoLe operation) for execution. Thus operation and administration 

via a terminal is possible. 


A paradigm for such a program is shown in chapter 4 of "DCAM COBOL Calls", 
Further information on this subject is to be found in the manuals 
"Operator's Guide" and "Generation of a Data Communication System". 


New traffic relations have been made possible by an extended hardware 
spectrum which is supported by BS2000 Version 4 and up. 
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_1 application — several tasks 


Stations: Application (group application) 


Terminal 1 application - 1 task 


(single application) 


Connections: aa Virtual connection Activities © Task 
Fig. 1-2 DCAM traffic relations 
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1.3 HARDWARE SPECTRUM FOR THE APPLICATION OF DCAM 


BS2000 Version 4 permits the use of a Large number of powerful hardware 

moduLes in the TRANSDATA data communication system. Fig. 1-3 contains an 
overview of all applicable devices. A new feature is the support of the 

966x Terminal Computer of the TRANSDATA computer family. 


The 8170 Local Cluster Controller is used for the first time. This enables 
terminals to be connected directly to the host computer. 
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Fig. 


oo 


SARRAN 


1-3 TRANSDATA hardware spectrum with BS2000 
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Legend: 


HC - Host Computer 

DXC = 4627 Data Exchange Control 

FEP = 968x Front-end Processor 

FEPR = 967x Remote Front-end Processor 
TC = 966x Terminal Computer 


1) Channel trunk 

2) Direct connection or data transmission Line 

3) Dual system switchover unit - alternate connection 
4) 8171 Remote Cluster Controller 

S) 8906 Interface Expander 

6) 8901 Medium-speed Concentrator 

7) 8902 Medium-speed Concentrator 

8) 8903 Medium-speed Concentrator 

9) Dedicated circuit 

10) Dial circuit (TELEX, DATEX, telephone network) 
11) 8170 Local Cluster Controller 
12) Local Loop 
13) Relocated Local Loop 


14) Multipoint network using data transmission facility (Modem N10) 


Terminals (including TRANSDATA 810 Terminal System) 


TRANSDATA 810 Terminal System only 


The number denotes the maximum number of connections. 


7.500 and 
7.700 systems 


| TRANSDATA 960 System 
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As previously mentioned, the user is supported by the virtual terminal 
feature when programming the terminals (see 2.3.4). Fig. 1-4 shows which 
which devices this applies to. 


Virtual terminals 


Line terminal Format terminal 


VTSU Virtual terminal support 


Printer terminal Data display terminal 


Model numbers of actual terminals 


8150? 8160% 
d n 81519 81619 
8110? 8152? 81624) 
8122? 81539)  975x9 
1) not supported Additional hardcopy devices 
diu 3) 8100,8120 
2) connectable 4 8121, 8122,9002,9003 
via 8112 5) 9001,9004 


Fig. 1-4 Virtual terminal support 
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2 BASIC CONCEPTS AND AN INTRODUCTION TO THE USE OF THE DCAM INTERFACE 


DCAM programs differ from other programs not only in that they use the DCAM 
interface, but access to the TRANSDATA data communication system also. 
determines their structure. Therefore, it is the object of this chapter to 
supply answers to the following questions: 


e Which characteristics determine the performance capabiLity of the 
DCAM interface? 


e What is the basic structure of a DCAM program? 
e What points have to be considered when pLanning a DCAM program? 


Prior to this, however, some basic concepts will be discussed to facilitate 
understanding. 


These are: 

e program, data, task 

e communication partner 
e symbolic addressing 


e virtual connection 


2-1 BASIC CONCEPTS 


2.1.1 Program, Data, Task 


In BS2000, the program and data areas and the task controlled by the 
program are generally administered as a single unit. For the sake of 
clarity, no distinction will be made between these three components in the 
following text. It is always this unit that is being referred to whenever 
a program or task is mentioned. The task's data area is important in the 
transmitting and receiving of messages since it is to and from this area 
that messages are transmitted. That is why the data area is referred to 
explicitly in certain passages. 


The specific structural and organizational characteristics of a 

DCAM program are dealt with in a separate section (2.3). 

Another section describes the particular situation that arises when a 
program controls several tasks (shareable programs/moduLes) (see 4.1.6). 
Program execution - the DCAM task - is also described in a separate 
section (see 4.1.6 and Fig. 2-1). 
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Fig. 2-1 The task as an administrative unit in BS2000 
2.1.2 Communication Partners 


In the TRANSDATA data communication system there are two different types of 
communication partner: 


terminals and applications. 
Applications can be: 


- DCAM applications, 
- UTM applications, 
- PDN applications. 


The programmer has no influence over the existence of terminal-type 
communication partners. Such communication partners are generated or 
removed either at communication system generation time or by means of 
administration instructions issued by the network administrator. 

The generation of DCAM application type communication partners is a 
function of the DCAM interface. | | 


Those users of the TRANSDATA data communication system who can set up 
virtual connections to other partners are referred to as communication 
partners in a vider sense. In the more restricted sense, this name is used 
to denote the two partners Linked by an existing virtual connection. 


The terminal is characterized by its technical implementation on the 

one hand and by the person operating it on the other. The interaction of 
these two elements, i.e. the device and the user of the device, implements 
the terminal communication partner at a given point in time. This 
communication partner can only maintain virtual connections to other 
partners and transmit and receive data via these connections with the means 
provided by the data communication system. 


The DCAM application exists exclusively in a host computer controlled 

by BS2000. It is defined by at Least one DCAM program and is generated by 
the data communication access method. It is administered by the 
communication access system as an addressable unit for incoming or outgoing 
messages and notifications and is canceled by program request. The DCAM 
application is the address at which tasks (programs) or groups of tasks are 
known to the data communication system. They thus become communication 
partners. 
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A DCAM appLication can be opened by one task (non-shareabLe) or by severaL 
tasks, i.e. a task group (shareabLe). The first opening task is the primary 
task. It may be followed by secondary tasks if required. Several DCAM 
appLications can be opened in one program. As each of them can be regarded 
separately, this feature is not discussed at greater Length in this manual. 
The DCAM application's name is estabLished when the application is 
generated (cf. example in Fig. 2-2). 


This name can be generated dynamically by the system, or a predefined 
name known to the data communication system can be used. The name of the 
DCAM application must be unique in the host computer in which the DCAM 
application is generated. 


Communication with other distributed processing applications is described 
in section 2.3.5. 


Non-shareable DCAM applications 
(can only be opened by one task) 


(shareable) 


Shareable DCAM applications 
(can be opened by more than one task) 


*) Task has opened several applications 


Fige 2-2 Examples of DCAM applications 
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2.1.3 SymboLic Addressing 


Two names suffice to address a partner: the name of the processor node the 
partner is connected to as a station, and the name of the communication 
partner (refer to the GLossary of TRANSDATA Terms). 


The names of the terminals and processor nodes are defined when the data 
communication system is generated. The names of the DCAM applications can 
be defined in the program when the applications are opened. In specific 
cases they can also be generated dynamically in the system (cf. Fig. 2-3). 
The symbolic addresses are converted in stages within the data 
communication system. Thus, the Logical network address is created one 
Level down and the physical address of the device another Level below that. 


However, the DCAM user only needs to know the symbolic addresses. ALL names 
used can have a maximum Length of 8 characters. The first character must be 
alphabetic or $, a, #. Characters 2 to 8 may also be digits from 0...9 
(ASSEMBLER name convention). A user application name may not begin with 

the dollar sign $, as this is reserved for internal system applications. 
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4 TRANSDATA 

data com- — 
munication 
system 


Front-end processor 


Connections 

to other 
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Concentrator | 


Terminal Terminal Terminal Terminal Terminal 


B Partner name 
ES] Processor name 


Fig. 2-3 Example of network configuration with symbolic addresses 
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2.1.4 Virtual Connection 


Before data can be transmitted by the data communication system, the two 
communication partners must first reach an agreement. This is done by the 
two communication partners stating that they wish to transmit data to 

each other, i.e. one partner begins with a connection request 
(acquisition). If the other partner accepts it, the connection is 
established. The data transmission modalities (such as the use of "virtual 
terminals") are specified during this operation. Virtual connections can 
exist between a terminal and a DCAM application and between two DCAM 
applications (cf. Fig. 2-4). 


In the data communication system a virtual connection is assigned: 

e a route in the network, | 

e buffer areas, etc. 

The virtual connection between two communication partners is documented 


in the relevant network components, thus guaranteeing a high degree of data 
transmission security. | 


Restriction: 
Virtual connections between data terminals are not yet possible. 


1 


Operator 


Note: 

It is of no signigicance 
whether applications A and 
B exist in the same host 
computer or in different 
host computers. 


Operator T 


Operator 


Fig. 2-4 Example of virtual connections 
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2.2 CHARACTERISTIC FEATURES OF DCRM 


2.2.1 Distribution of Incoming Messages 


There is a choice of two methods for the distribution of messages arriving 
for a DCAM application: 


e distribution via originator-oriented queues or common-receiver queues 
e distribution via distribution code oriented queues 


The first method is suitable both for shareable and for non-shareable DCAM 
applications, the second only for shareable DCAM applications. 


2.2.1.1 Originator-Oriented Queue and Common-Receiver Queue 


A queue for incoming messages is set up for each established connection 
enabLing originator-oriented access to the messages. Access in the order of 
arrival (regardless of the message originator) is implemented by another 
queue, the common-receiver queue. A message is always entered in one of the 
two queues. The user specifies in the program which queue is to be accessed. 
This is possible during connection setup and can be respecified for 
subsequent processing each time a message is transmitted or received. 


In this vay, messages can be fetched onLy from the originator-oriented 

queue for a definable period of time. In the case of shareable applications, 
the Link between a task and a virtuaL connection is established in this 

way. This Link is canceled again when the common-receiver queue is used. 


Fig. 2-5 provides an overviev. 


Task 1 has specified (during Logon or during the Last transmission or 
reception operation) that it vants to receive messages via connection A, 
and accesses the associated queue with receive macros. The same applies 

to task 3 and connection C. Messages from connections B and D are received 
by task 2 but can also be received by other tasks. 
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*) Originator-oriented queues 
**) Common-receiver queue 


Fig. 2-5 Example of queue access 


2.2.1.2 Distribution Code Oriented Queues 


It is presumed that the task group is controlled by programs vith different 
Capabilities, i.e. that each program can only process certain messages. 
The message/program (task) Link is established by means of a code which 
is contained in the message itself. The user can select the code and 
specifies specific codes when the virtual connection is established 

(for a detailed description of the various options refer to 3.2.1.4). 

A separate queue is created for each code group, and the 

allocation of the queues to the programs is controlled by the primary 
task (special macros are provided for this purpose, see 3.3.4). 

A distribution name is defined for this purpose when the application is 
opened. It is assigned to the distribution codes in order to Link them to 
a task. : 


The name can be the same for several tasks, as, for instance, when one 
program controls more than one task. DCAM then passes on messages to the 
various tasks in accordance with the FIFO principle (first in - first out: 
the first entry in the queue will be the first one processed). 
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When the communication partner enters the code defined at connection set- 
up time or Later, he will reach the task whose distribution name has been 
assigned to this code by the primary task. 


Thus the primary task controls 


e the assignment of distribution codes to a connection: 
when setting up a connection, it determines vhich codes are to be used 
and it can redefine these codes for an active connection at any time via 
a new macro call. 


e the assignment of the distribution codes to a task by means of the 
distribution name. 


Messages which cannot be delivered because their code is not allocated or 
is invalid are delivered to the primary task. 


© Fig. 2-6 shows an example of queues for distribution code groups 
containing only one code each. 
As messages with the same code arrive from different partners, originator- 
oriented access to these messages is also possible. The distribution 
name DISTRIB1 is assigned both to task 1 (primary task) and to task 2. At 
this point the FIFO rule (see above) comes into effect: messages with 
the codes CA and CF will be passed on in the sequence of their arrival to 
the next task issuing a receive call. Messages with the codes CD, CX and 
C$ are distributed to task 1 because they are not assigned to any other 
task. ,——— — - un — 


Distribution NDISTRIB 1 DISTRIB N DISTRIB 2 DISTRIB 3 DISTRIB 4 
name 


" Distribution code-oriented queues **) Default option 
Fig. 2-6 Example of access to distribution code-oriented queues 
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2.2.1.3 Implicit Distribution Code 


If a sequence of messages contain the same distribution code it is 
sufficient to specify this code in the first message. For this purpose the 
primary task defines a code indicator character which indicates that a 
distribution code is incLuded in a message or message sequence. The 
distribution code immediately follows this character. In this case it may 
be no more than 7 characters Long. 


If messages without a distribution code are received, they are allocated 
according to the Last distribution code received. For subsequent messages 
DCAM implicitly assumes the distribution code Last in force. This applies 
until the partner sends a message in which a distribution code is explicitly 
specified. 


If a code indicator character has not been defined by the primary task, 
then a distribution code must be included in each message. Otherwise they 
will be delivered to the primary task. 


The same applies if the user omits to begin a sequence of messages with 
at Least one message containing a distribution code. 


2.2.2 Calls and Notifications 


The functions provided by DCAM consist of calls with which the BS2000 user 
can effect the execution of certain actions, and of asynchronous 
notifications (see 4.1.5) vith which DCAM informs the user about certain 
events in the communication system. 


The calls issued to DCAM all begin with the Letter Y. They are available 
either as macro calls (ASSEMBLER) or as COBOL calls. The calls are 
terminated after execution or when a defined processing period has elapsed 
(synchronous execution). It is also possible to have control returned 
after the call has been issued (asynchronous execution). Call termination 
is indicated by an asynchronous notification which can be tested in the 
program. A separate (contingency) routine can also be initiated by the 
arrival of the notification (see 4.1.3). This asynchronous processing 
serves especially to make use of the waiting periods. 


2.2.3 Security Concept 


2.2.3.1 Protection against Unauthorized Access 


A DCAM application can be protected against unauthorized connection of a 
task within the host computer. If the application is to be non-shareabLe, 
the connection of a secondary task is not possibLe. In the case of 

a shareable application, unauthorized connection of a secondary task can 
be prevented by means of a passvord. 
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Predefined applications can already be protected against unauthorized 
opening (by a user password) in the resource definition file at the system 
generation stage. This RDF password must be provided by the primary and 
secondary task. 


The unauthorized setup of a virtual connection can be prevented within 

the data communication system. Firstly, by DCAM applications not accepting 
connection requests, either permanently or for a certain period of 

time, and secondLy, by requiring that a passvord be specified in a 
connection request. Finally the user can opt to accept or reject a 
connection request on the basis of the connection message and/or the 
address of the requesting partner. 

These procedures ensure that erroneous or intentional illegal access can be 
Vb icd f Passwords can also be dynamically altered for this purpose 

see 3.4). 


2.2.3.2 Data Security 


Data protection is a further feature of the security concept. On the 
physical data transmission Level, protocols with error recovery are 

used (HDLC, MSV1, MSV2, LSV1, NEA) guaranteeing the integrity of the 
transmitted data by means of suitabLe error detection and automatic error 
correction facilities (cf. Fig. 2-7). 


DCAM/BCAM 


Transmission of data (message with sequence number) 


+ nd 3 ) Positive acknowledgment of data communication procedure (ACK) 
po» 2 Positive acknowledgment of message |/O 
E] E: Transport acknowledgment 
* The transport acknowledgment is generated here when the 


message has arrived at the destination (teminal) i.e. has 
been acknowledged positively. 


C Fig. 2-7 Example of message acknowLedgment 
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The allocation and distribution of the storage capacities to virtual 
connections rule out mutual interference (e.g. by memory monopoLlization) 
and introduce a further security factor. In addition to this, the user can 
request transport acknowLedgments for transmitted messages. He can opt 

for negative and positive, only negative or no acknowledgments. A negative 
acknowledgment is generated when a message cannot be delivered to its 
destination, regardless of the reason for this. A positive acknowledgment 
is generated when the message arrives at the destination (i.e. entered in 
the receiver's data area). The originator, which added a sequence number to 
the message, receives the acknowledgment, which was generated at the 
destination and transported through the network, under this number. 


The originator can receive the transport acknowledgment Like any other 
message. However, he can also receive the transport acknowledgment as an 
asynchronous notification (see 4.1.5 as well). In a task group, there is 
the further possibility of always transferring the transport acknowledg- 
ment to the primary task or to the task requesting the acknowledgment 
(see also 3.3.2). 


Restriction: 


COBOL users cannot receive transport acknowledgments as asynchronous 
notifications. 


2.2.5.3 Express Messages 


Another aspect of data security, the solution of conflict cases, is also 
provided for. Unhindered data transmission is ensured in the TRANSDATA data 
communication system by connection-oriented data flow control and capacity 
distribution. The existing buffer areas are used by each connection only 
being allowed to occupy a certain subarea. Thus, the buffers cannot be 
compLeteLy occupied by the data of one connection. Hovever, to ensure that 
a connection remains operabLe in the case of blockage affecting it, short, 
fixed-Length express messages can be delivered to the destination as 
high-priority messages which bypass the data flow control. Such messages 
"Overtake" the others, so to speak. If the destination so desires, the 
express message is transferred to it immediately as an asynchronous 
notification (cf. 4.1.5), otherwise it is entered as far forward in the 
queue as possible. Express messages cannot be transmitted if the connection 
is operating with a virtual terminal. 


Restriction: 
COBOL users cannot receive express messages asynchronous notifications. 


2.2.3.% Data Flow Control 


The system can reduce the Load on an overLoaded connection by temporarily 
interrupting the transmission of messages. This can affect both normal and 
express messages. 

AS soon as the connection is ready for use once more, the user can be 
informed, by means of a GO signal, that the jam has been cleared and that 
transmission of messages may be recommenced. 
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2.3 PLRNNING PROGRRM STRUCTURE 


When a DCAM program is being planned, its function may already be 

defined; however, it is also possible that, due to the facilities offered, 
the problem will be re-formulated or even formulated for the first time. 
The following functions are typical of those handLed by a DCAM program. 


2.3.1 Functions of a DCAM Program 


DCAM programs are created in order to implement transaction processing in 
BS2000. As opposed to timesharing, its object and impLementation are 
compLeted vhen the transaction task is started. 

Moreover, DCAM programs usually solve probLems which can be solved with 
specific BS2000 facilities (see Table 2-1) 


Transaction mode functions Supported in BS2000 by: 

Dialog between a few - Synchronous processing of DCAM calls 
individual terminals and - Management of primary tasks 

a program (non-shareable DCAM applications) 

Dialogs in individual - Queues for access to specific 

steps or in a sequence or any partners 

of inquiries and - Accompanying information on the connection 
responses for transfer vith the message (containing, 


for example, the address of a memory area) 
Restriction: cannot be used in COBOL. 


Processing of inquiries - Asynchronous processing of DCAM 

from a Large calls with P1 EVENTING AND 

number of terminals CONTINGENCIES 

by one program system - Management of primary and secondary tasks 


(shareable DCAM application) 
- Support of reentrant programming 


Data transfer from programs - Synchronous or asynchronous processing of 
in the same or in DCAM calls 
other host computers - Event-controLLed processing with 
of the TRANSDATA data P1 EVENTING AND 
communication system CONTINGENCIES 
Forwarding of data to - Use of Local or common memory areas with 
exclusive data processing COMMON MEMORY and serialization 
programs in the same host - Coordination by means of 
computer and coordination P1 eventing, inter-task 
of the cooperation communication or user 
syitches 
Formatting of messages - Support by means of conversion 
for Line-by-Line output ^ from virtual terminals to 
or forms display on CRT physical characteristics of 
screens individual terminal types (VTSU) 
Utilization of specific - Possibility of "physical" 
terminal characteristics programming of terminals 
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Transaction Mode Functions Supported in BS2000 by: 


Processing of inquiries 
in the shortest possible 
time to provide the 
terimnal user with 
good response times 


Processing of different 
requests from a terminal 
in one program system 


Data security 


Protection against 
unauthorized access to 
programs or program 
systems or to files 


Task control in timesharing mode 
Rapid file access with user PAM 
Reentrant control of programs with 
shared code in conjunction with good 
memory usage and Low paging rate 


Message distribution via distribution 


code oriented queues 


Transmission of transport acknowledgments 
for messages 

Transmission of express messages 
Prevention of multiple file 

access to single records: 

ISAM shared update 

or blocks (half pages): 

user PAM shared update 


Password protection of the DCAM 
application 

Password protection of the virtual 
connection 

Passwords for the protection of 
files against unauthorized reading, 
writing and processing 


Table 2-1: Transaction processing with BS2000 


The programmer has at his disposal: 


the services of the TRANSDATA DCM (Data Communication Methods) interfaces, 
of the Control System and of the data management system DVS. 


It is expedient to subdivide DCAM programs. In the case of shared-code 
programming, a subdivision into operation code, constants area and dynamic 
work area is required. This also facilitates documentation and subsequent 


maintenance. 


In the case of simple functions, such as the operation of a small number 
of terminals, single-step interactive communication, no special security 
requirements etc., programs can be subdivided into a communication part and 


a data processing part. 


More compLex functions require extensive interaction of the various 
interfaces and therefore only allow demarcation in accordance with the 
specific problem It is beyond the scope of this manual to set forth any 


general rules on this subject. 


By providing for program systems vhich 


control one primary task and several secondary tasks, the system supports 
the structuring of complex functions. It is also possible to subdivide the 
coding into ASSEMBLER and COBOL modules. 


Before going into the specific functions of a primary task and of the 
secondary tasks in detail, it seems expedient to List the essential 
elements for the creation of a DCAM program. 
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2.3.2 Basic Structure of a DCAM Program 


Two preparatory stages have to be completed in a DCAM program or program 
system before actual data transmission can begin: 


ist stage: Opening a DCAM appLication. 


To allow a program to be addressed by other communication 
partners, it must open at Least one DCAM application. The 
name that is defined at that point forms, together vith the 
name of the processor (processor node), the symbolic network 
address in a network region. Furthermore characteristics 

of the DCAM application are defined, and passwords are 
specified. The statement that executes this stage is called 
YOPEN. 


e 2nd stage: EstabLishing a virtuaL connection. 


Before data transmission can take place between two 
communication partners, one of the partners must send 

a request to establish a virtual connection to the other, 
who must accept this request, i.e. a virtual connection 

must be set up. Buffering and distribution of the messages 
are carried out according to the specifications made at this 
point. Moreover, it is necessary to specify what 

kind of message editing is desired or whether the user 

will take care of message editing himself. In addition, the 
communication partners can exchange accompanying information. 
The statement for this stage is YOPNCON ACCEPT (accept 
connection request) or YOPNCON ACQUIRE (output connection 
request). 


Following the two preparatory stages, messages can be received with 
YRECEIVE and transmitted vith YSEND. 


After completion of data transmission, a virtual connection is either 
closed down explicitly by the program with YCLSCON or implicitly by either 
the closing of the DCAM application by means of the YCLOSE statement 

C or the termination of the program. In addition, a virtual connection 
can also be cleared down from the terminal by inputting an agreed end 
criterion which must initiate the execution of YCLSCON in the program. 
Abnormal termination of a virtual connection due to disconnection of the 
terminal, Line failure, etc., can be reported to the progran. 
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Optional: Definition of dynamically-assignable 
eng NAT and the user field with 


a-— am — ee — mmm m —MÀíÁáQ m m een tele | 
| 
| 


os... 


*) in ASSEMBLER only; with COBOL the corresponding 
command mode statements should be used 


Fig. 2-8 Schematic Layout of a DCAM program 


Dynamic name assignment can also influence the structure of the program. 
The dynamically allocated names, passwords and the user field must be 
entered in the CLT (Communication Link TabLe) prior to the opening of the 
DCAM application or connection setup. A separate program or a Leader should 
therefore contain the YAPPL or YCONN calls or commands /APPLICATION and 
/CONNECTION should be used accordingly (cf. Fig. 2-8). 


Restriction: 


The YAPPL and YCONN calls are not available for COBOL programs. 


After each call issued to DCAM, a check must be made to see whether it 

was properly executed. Feedback information (FDBK) is provided for this 
purpose. The result of the check may be that a call is repeated or has to 
be executed in a different vay, that other measures have to be taken, or 
that the program run has to be terminated. The error recovery routine can 
immediately follow the call but, as it is usually the same or similar 
measures that have to be taken, it will be coded only once and used 
repeatedly. In this case, a common error recovery routine would have to be 
created. 
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2.3.3 ControL of Primary and Secondary Tasks 


A primary task, i.e. the first task to open a DCAM application, contains 
all the essential DCAM functions (see preceding section). In a task group 
this task is automatically the controlling task which contains the 
connection function, distribution code control, and password definitions, 
in short everything that concerns the task group as a whole. 


At YOPEN time, VERIFY can be used to check that the task is chronologically 
the first to open the application. The primary task can transmit and receive 
messages just as the secondary tasks. When the DCAM application is closed in 
the primary task, it is also closed for the secondary tasks. 


The structure of the program controlling the primary task is dependent on 
the answers to various questions which are Listed in Table 2-2. 


Questions concerning the Measures taken if the answer to 
structure of a program the questions is positive 
controlling a primary task 


- Is the configuration The primary task should do all the processing; 
to he operated small? secondary tasks are not required and not 
- Is the mean time permitted (non-shareable DCAM application) 


between the arrival of 
two messages consider- 
able (Low workload)? 

- Is the job so Limited 
in scope that subdivi- 
sion into different 
processing modules is 
not necessary? 


- Is the mean time The primary task and the secondary tasks should 
between the arrival of be controlled by a shared-code program. As the 
two messages short? primary task must carry out specific functions, 

- Is the configuration this should be provided for in the program. 
Large? | Or alternatively, the program should be 
Is a short processing structured on a modular basis and only specific 
time required? modules be utilized and Loaded by the tasks 

- Do the inquiries ar- The primary task should control distribution 
riving via virtual code allocation to the secondary tasks and 
connections require thus message distribution. It will define 
different types of a password for the connection of secondary 
processing? tasks. It will check messages that cannot be 

- Do the distribution delivered to a destination within the group. 
codes in the message The primary task will have further means at its 
change? disposal for the control of the task group 

- Are passwords to be within the framework of common memory, 
used to control the P1 eventing, etc. 


connection of a task 
to a DCAM application 
for security reasons? 

- Is all data to be 
checked? 

- Are additional control 
functions to be 
implemented? 


Table 2-2: Control of a primary task 
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A secondary task, i.e. a task vhich opens a DCAM application but is 

not the first to do so, has no influence on the characteristics of the 
DCAM application, and may have to specify a password in order to join the 
group. It can use VERIFY to check whether it opened the application Later 
than the primary task. It can neither establish nor close down virtual 
connections. It has no control function within the group. Its function 

is to transmit and receive messages and to process them. Therefore, 

the only aspect of significance with regard to the structure of the 
program is the vay in which YSEND, YRECEIVE or YSENDREC calls are issued 
and processed. Attention must be paid to any controlling actions by the 
primary task (connection control, distribution code allocation of incoming 
messages, etc.). If the DCAM application is closed in the secondary task, 
this has no effect on the other tasks of the group. 


2.3.4 Access to Terminals 

An important question in the planning of DCAM programs is how the 
terminals are to be accessed. | 

The DCAM programmer has a choice of two methods: 

© physical programming 

e use of virtual terminals. 

Physical programming requires the operation of a terminal with the control 


characters it understands (see User's Guides for individual terminals). The 
programmer wins considerable flexibility, but has also the inconvenience of 


operating with control characters. The virtual terminals relieve him of this 


inconvenience because all essential functions can be implemented with these 
standardized terminals (but not with Locally connected terminals). 


The virtual terminals are user service software modules in the TRANSDATA 
data communication system. At the Logon stage, the communication partners 
agree on which virtual terminal can or should be used. Certain aspects 
have to be clarified in order to do this, such as whether a hardcopy unit 
is connected to a display terminal or a Light pen is to be used. 


The programmer has a choice of two virtual terminals: the Line terminal 
and the form terminal. 
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2.3.%.1 Line Terminal 


The Line terminal is impLemented in the system by the VTSU (Virtual terminal 
support) module. The user only has to order the data into Logical Lines 

with a device-independent “new Line" control character. Conversion of these 
Lines into the actual Lines of the terminal is performed by the system. 
During this procedure, Logical Lines may be subdivided into further Lines 

if the available Line Length of the device (typewriter terminal, data 
display terminal, printer terminal) is not sufficient. 


When a program receives messages from a Line terminal, the end of the 
Lines is indicated by the same device-independent "new Line" character. 
During input and output, the beginning of a message is also the beginning 
of a Line and the end of the message the end of the Line. 

The Line terminal only accepts printable characters. 


Fig. 2-9 shows the message path through the system when the Line terminal 
is used. 


User: | System: 
| : - DOM ? ue Network 


Fig. 2-9 Transmitting and receiving data to be represented in Line format 


The following Logical control characters are also available to the user: 
e new page 

e mark-in 

e mark-out 

e shift-in 

e shift-out 

as well as 

e output function key code 

e structuring of output. 

Additional record control character: 


e Logical end-of-Line character 
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Logical display control characters: 
e marked display 2 

® marked display 3 

e marked display 4 

e blanking 

e start proportional spacing 

e end proportional spacing 

e start unprotected area 

e start protected area 

e end protected area 

Further Logical control characters: 
e delete character 

@ backspace 

® current position 

e vertical position (Line) 

e horizontal position (column) 

e control sheet draw-in/eject 

e Left margin 

e Line spacing 

e character spacing 

e maximum Line Length J 
© maximum number of Lines 

e substitute character 

e subscript Line 

e superscript Line 

Physical control characters: 

e ESCAPE 

e transparent transfer of first character 

e horizontal tabuLator 


e vertical tabulator 
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The control character "new page' in the output text of a message results 
in: 


e output of a Logical end of .Line 


e page throv, i.e. 


for data display The screen is cleared 
terminals: Positioning to start of screen (not with 8161 
using roll-up) 


for printer terminals: Page throw 

for typewriter terminals: Paper advance (10 Lines) 

The control character 'mark-in' causes the text which follows to be output 
in italic script or in flashing characters. This applies until the control 


character 'mark-out', "new Line" or ‘new page" is encountered, or until 
the end of the message concerned. 


The control character 'shift-out' switches to the second character set, if 
one is available, The user can subsequently switch back to the standard 
character set by means of 'shift-in'. 


The function 'output of function key code' enabLes the user to have the 
device independent code of function keys or short messages output as the 
first byte of a message. 


The function 'structuring of message' enables the user to specify whether 
the whole message, or each Logical Line of the message, is to be treated as 
a structural entity. There follows a brief explanation of the two 
structural types, using the 816x Data Display Terminals as an example. 


Taking the message as the structural unit means: 


The message Length is restricted by the system output buffer. By modifying 
one character the whole message can be transmitted back again. 


Taking the Logical Line as the structural unit means: 

The message Length is unrestricted, provided the Logical Lines are no 
Longer than 255 characters. Logical Lines can be modified individually, 
and thus transmitted back selectively. 


The 'hardcopy' function enabLes the user to have the output on the screen 
Logged simultaneously on a hardcopy unit. 


The control character "Logical end of Line" resets a special terminal 
display to standard display (standard, first character set, unprotected). 
The defined end-of-Line character is output. 


The control character ‘start of protected area’ outputs subsequent text 
characters as protected text on the screen, i.e. they cannot be overwritten 
or transmitted to the system. 


. The control character ‘end of protected area’ causes subsequent text 
characters to be output unprotected to the terminal. 


The control character ‘delete character' causes a text character to be 
deleted from the output text and not to be transmitted to the terminal. 


The control character ‘backspace’ causes the next text character to be 


superimposed on the preceding character. This enabLes a character which is 
not in the character set to be displayed. 
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2.3.4.2 Form Terminal 


The form terminal requires the use of the terminal mapping support 
modules and macros. 


The forms are described with the macros of the FORM interface. In COBOL 
programs, this must be done separately; the forms are Later Linked into the 
COBOL program as separate modules. Symbolic description maps are provided 
in ASSEMBLER and COBOL for the processing of the form fields. The program 
cooperates with a mapping routine for the transmission and reception of 
messages. The forms are edited by this routine for output on the physical 
terminals (typewriter terminal, data display terminal). Messages from the 
terminal are also converted by this routine (cf. Fig. 2-10). 


User: Communication access J 
method: | 


Pu are eine, 


Formatting routine 


EN] a 
| —— 


*) Generation need not be separate in ASSEMBLER programs. 
**) The formatting routine is linked into the user program. 


Fig. 2-10 Transmitting and receiving formatted data 


If desired, the following additional functions can be executed for the Line 
terminal and for the form terminal: 


e upper case/Lover case processing 
a processing of backspace characters 
e simultaneous output on hardcopy unit 


e sounding an audible alarm 
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2.3.5 Implementation of Distributed Processing 


The TRANSDATA Communication System allows communication between: 

i terminals and applications 

e applications and applications 

Here, both terminals and applications can form part of an extensive 
network, comprising. host computers, front-end processors, remote front-end 


processors and terminal computers. 


Apart from the connection to terminals, this opens up the following 
possibilities for a DCAM application: 


The partner may be 
" e a DCAM application 
e a UTM application 


e a PDN application 


2.3.5.1 A DCAM Application as a Partner 


The DCAM application as a communication partner is described in chapter 3. 
The existence function of a DCAM application is described in section 3.1. 
Establishing a virtual connection between DCAM applications is described 
in section 3.2, while data transmission between DCAM applications is 
explained in section 3.3. 
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2.3.5.2 A UTM Application as a Partner 


Communication between a DCAM application and a UTM application is possible 
if the DCAM has been generated as a communication partner for the UTM 
application and if a virtual connection has been established between the 
two applications. This is true whether the applications are in the same or 
in different host computers. 


There are three different ways of establishing a connection between a DCAM 
and a UTM application: 


e The UTM application has been generated so that when it is started a 
connection is established. The connection is set up if the DCAM 
application exists at this moment and explicitly accepts the connection 
request. 


e The UTM appLication has been generated so that connection requests from 
the DCAM application are accepted. The connection is established if 
both applications exist and if the DCAM application has issued an 
explicit connection request. 


e A UTM administration command can be used to cause a connection request 
to be issued to a DCAM application. 


When transmitting data care must be taken that the UTM application has been 
provided with a structure. The UTM application is composed of subroutines, 
which can be addressed via the transaction codes which they have been 
allocated. When a transaction is started the data must be included at the 
beginning of the transaction code. 


2.3.5.3 A PDN Application as a Partner 


A PDN application is generated in the operating system of a terminal 
computer using the KOGS generator Language. The PDN application comes into 
existence with the arrival of a message for the PDN application: 


e from a connected terminal 
e from an existing PDN application in the same computer, 


e and with the arrival of a connection request from another communication 
partner in the TRANSDATA network. 


PDN applications can also establish virtual connections themselves. 


When establishing connections and transmitting data, it should be noted 
that DCAM handles a PDN application as an application. It follows 
accordingly that the system does not carry out message handling. In 
particular, the user cannot employ any virtual terminals. 
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3 DCAM FUNCTIONS 


The functions provided by DCAM can be subdivided into 4 groups: 
e Existence function | 

e Connection function 

e Data transmission function 

e Name assignment function 


These functions are described in detail in the following. The Layout of 
this chapter corresponds to that of chapter 3 of the ASSEMBLER Programmer's 

e Guide (see "DCAM Macros") and the COBOL Programmer's Guide (see "DCAM 
COBOL Calls"), where the corresponding calls are Listed along with the 
required operands. 


3-1 EXISTENCE FUNCTION 


The existence function of the DCAM interface. performs the following 
operations: 


e Opening or generation of a DCAM application (YOPEN). 
This is the basic function of DCAM, and is executed in. different ways 
depending on the type of DCAM application involved. 


e Changing the status (YSETLOG) of a DCAM application. | 
This function can be used to dynamically change the state of the 
DCAM application, i.e. its readiness to process connection requests. 


C e Testing the status (YINQUIRE) of a DCAM application. 
As dynamic changing (see preceding item) is possible, this inquiry 
function is also provided. 


e Closure of a DCAM application (YCLOSE). 


The DCAM application is closed automatically at the end of the program; 
this function can close it at any point in time during the program run. 
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3.1.1 Opening a DCAM AppLication 


A DCAM application is generated when the first program opens it. At the 
same time the application is defined as shareable or non-shareable. A 
non-shareable application can only be opened by one program and is also 
closed by that program. A shareable application can also be opened by other 
programs (secondary tasks). These, however, only Link up with the 
application and have no influence on the definitions made by the first 
program to open/generate the application (primary task). It is necessary to 
specify whether the distribution code oriented queues are to be used for 
message distribution. This results in different variants of the YOPEN call. 


Specifications for dynamic name assignment are dealt with in a separate 
section (see 3.4). 
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3.1.1.1 Non-Shareable DCAM Application 


A DCAM application which is to be non-shareable (NSHARE) can be opened by 
only one task. A second attempt to open this application will be rejected. 
Within the bounds of this restriction, it is expedient to Lay down further 
definitions, which may vary depending on a number of factors (see Table 


3-1) e 
Requirements Definitions 
The name of the DCAM application is Name of the DCAM application 


not to be generated by the communica- 
tion access method. 


Only the DCAM application is to issue Attribute NLOGON: 
© connection requests (NLOGON). In this Connection requests will not be 
case, the partners must either be accepted. 
terminals or DCAM applications 
accepting connection requests. 


It is not known in the program Attribute LOGON: 

whether and when a partner wishes Connection requests will be 
to Log on or the partner is not accepted. 

known. 

The application is protected by Password USEPW 


a password in the RDF (APPPW=, see 
the manual Generation of a Data 
Communication System). 


Unauthorized connection requests are Password (LOGPASS), which has to 


to be rejected automatically. be specified by the communication 
partners. 

Asynchronous notifications are Reference to the identifier of a 

to be accepted. — contingency routine generated when 
an ENACO call vas issued (see (8)). 
When a notification arrives, this 

C routine is activated. 

Note: unnecessary for COBOL 

Certain new functions belonging to a Specification of DCAM version 

DCAM version from 8.0 onwards are to number (DCAMVER). 

be used. 


TabLe 3-1: Definition of non-shareabLe DCAM applications 


~ 


Restriction: 


When COBOL is being used, the name of the DCAM application must always 
be specified by the user. 
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3.1.1.2 Primary Opening of a ShareabLe DCAM AppLication 


A shareable DCAM application can be opened by more than one task. The first 
task to open it is the primary task. Unless otherwise specified, messages 
are not distributed via distribution codes (SHARE, NDISCO), i.e. the 
originator-oriented or common-receiver queue(s) are used. The name of the 


DCAM application must be defined in the program. 


For further definitions, 


which are dependent on various factors, see Table 3-2. 


Requirements 


The task is to be the first opening 
task as it is to fulfill the functions 
Of a primary task. If it is not the 
primary task, the YOPEN is to be 
rejected. 


It can be taken for granted that the 
task is the first opening task, or all 
programs Linking to the application 
have the same program Logic. 


The possibility of unauthorized 
connection of secondary tasks cannot 
be excLuded and is therefore to be 
prevented. 


Only the DCAM application is to 

issue connection requests (NLOGON). 
In this case the partners must either 
be terminals or DCAM applications 
accepting connection requests. 


It is not known in the program 
whether and when a partner wishes to 
Log on, or the partner is not known. 


Unauthorized connection requests are 
to be rejected automatically. 


Definition 


Check with VERIFY = PRIMARY. 


No check, 
i.e. VERIFY = NO. 


Password USEPASS, which must be 
specified by the secondary tasks 
for subsequent opening. 


Note: 


If the DCAM application is already 
protected by a password (APPPW-, 
see manual "Generation of a Data 
Communication System") in the RDF, 
the USEPASS password must be 
identical to that APPPW- password. 
The USEPW operand is then also 
analyzed in the primary task; 

it must contain the RDF passvord. 


Attribute NLOGON: 
Connection requests will not be 
accepted. 


Attribute LOGON: 
Connection requests will be 
accepted. 


Password (LOGPASS), which must be 
specified by the communication 
partners. 


Note: 
LOGPASS and USEPASS cannot 


be changed in an existing DCAM 
appLication. 
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Requirements Definition 

Transport acknovLedgments for this PRIMTASK attribute for the 
application are as a rule processed in transfer of transport 

the primary task. acknowLedgments. 

Transport acknowledgments are REQTASK attribute for the 
processed by the task that sent the transfer of transport 
message with the corresponding acknowLedgments. 


sequence number (SEQNO). 


This application does not process NOTACK attribute: positive or 
any transport acknowledgments negative transport : 
because user security procedures are acknowLedgments are not. 
to be impLemented. transferred. 
e Neu functions beLonging to a DCAM Specification of the DCAM version 
version from 8.0 onwards are to be number (DCAMVER). 
used. 
Asynchronous notifications are to Reference to the identifier of a 
be accepted. contingency routine generated 


when an ENACO call was issued. 
When a notification arrives, this 
routine is activated. 

Note: not necessary for COBOL 


Table 3-2: Description of shareable DCAM applications opened by the 
primary task ! 


3.1.1.3 Primary Opening - Use of Distribution Codes 


The primary task that opens a DCAM application can specify that a 
distribution code is to be used (SHARE,DISCO) in place of the default 

© option for message distribution. This is especially useful if the programs 
involved perform different jobs but are accessed by the same partners. ALL 
the tasks involved must then define distribution code names permitting 
association of distribution code(s) and tasks (DISNAME). For further 
definitions, see Table 3-2. mic Meee 
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3.1.1.4 Secondary Opening 


A task which is not the first to open a DCAM application must comply with 
the definitions Laid down in the primary task. Consequently, it must use 
the defined name of the DCAM application and also set ATTR=SHARE (shareable 
DCAM application). The default option provides for message distribution 

via the originator-oriented or common-receiver queues. Further definitions 
are Listed in Table 3-3. 


Requirements Definitions 

The primary task has defined Password (USEPW) for Linking up 
a passvord to guard against with the DCAM application as 
unauthorized access or the specified in the primary 
application is protected by an RDF task or RDF. | 

password. 

The task must always be a secondary Check with VERIFY=SECONDARY. 


task as this is stipulated in the 
program Logic; if necessary, YOPEN 
is to be rejected. 


It can be taken for granted that the No check, thus VERIFY=NO. 
task is not the first to open the 

application, or, alternatively, the 

program Logic checks this 


requirement. 

Asynchronous notifications are to Reference to the identifier of 

be accepted. a contingency routine generated 
Restriction: when an ENACO call vas issued. 

There are no asynchronous When the notification arrives, 

notifications intended for the this routine is activated. 


secondary task at the COBOL interface. 


The primary task specified a DCAM Specification of the same DCAM 
version number on opening the version number as in the primary 
application. task (DCAMVER) 


Table 3-3: Description of shareable DCAM applications opened by a 
secondary task 


3.1.1.5 Secondary Opening - Use of Distribution Codes 


During secondary opening of a DCAM application, the same message 
distribution method must be used as during primary opening by the primary 
task, i.e. the distribution method is uniform vithin a task group. 
Distribution codes are used in this variant which means that the SHARE and 
DISCO attributes are specified in the primary task. The same DCAM 
application name and the SHARE attribute must be specified in the secondary 
task. Furthermore, a name must be defined (DISNAME) to be used for 
distribution code aLLocation. ALL. further definitions are Listed in 

Table 3-3. 
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3.1.2 ALtering the State of a DCAM AppLication 


The various states of a DCAM application are shown in Fig. 3-1. 


opening 
Alteration of 
the DCAM ap- 
plication state 
by means of 
primarv task) | YSETLOG 
duo uf | Closure by START 
e asu reor ; ; the primary 
vue qc cuu 4 task 
| L Primary 
: CSTE SNR GER GENK) CERES 
i opening 
Closure by 
L CIRM DLE EERE COA GE BE Ce 
the primary task 


Fige 3-1 DCAM application states 


A DCAM application can be designed not to accept connection requests 
(NLOGON attribute). This attribute cannot be altered Later for an existing 
DCAM application. 


If, on the other hand, such requests are to be accepted (LOGON attribute), 
this can be temporarily prevented. 


Connection requests are reported to the DCAM application, or, if several 

© arrive, posted in a queue, until the primary task notifies by means of the 
YSETLOG call that it no Longer wishes to accept such notifications (STOP), 
possibly because the maximum number of permissible connections has been 
reached or because it wishes to issue its own requests for some time. If 
conditions change, the primary task can at any time reestablish the 
original state, i.e. requests will no Longer be rejected but will be 
accepted by the primary task or posted in the queue (START). 
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3.1.3 Testing the State of a DCAM AppLication 


With the YINQUIRE call, the user can test the state of the DCAM application 
that he himself has opened and also the state of a DCAM application which 
was opened in the same host computer and whose name he knows. 


He should-use the "APPSTAT" variant of the YINQUIRE call for this purpose. 


3.1.4 CLosing a DCAM AppLication 


The DCAM application can be closed in two ways: 


e implicitly by terminating the program in which the DCAM application was 
opened (normal or abnormal termination or task abortion) 


èe explicitly by means of the YCLOSE call or by means of the /SHUTDOWN or 
/BCLOSE operator commands. 


Explicit closing with YCLOSE will be necessary when, for example, a program 
is to process several DCAM applications consecutively or if definitions are 
to be changed during execution. The application can be opened again by the 
primary task with new definitions (name, attributes etc.) after being 
closed. (See 3.4 for name assignment function. ) 


The secondary task can close the application at any time without any 
consequences for the other tasks in the group. 


Closure by the primary task results in: 

e the DCAM application being canceled; 

e secondary tasks being informed through initiation of the COMEND 
contingency routine (see 4.1.5) or by feedback information for an 
incomplete call or the next call}; 


e all existing connections being cleared down. 


This also means that data which has already arrived but has not yet been 
accepted is no Longer accessible. Pending connection requests are deleted. 
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$.2 CONNECTION FUNCTION 


The requirement for data transmission is the setting up of a virtual 
connection between the communication partners. This is the second 
preparatory step after a DCAM application has been opened. 


The connection function performs the following operations: 


e Virtual connection setup (YOPNCON). 


connection requests can be output and incoming requests can be accepted. 


e Interrogation of entries on partners and connections (YINQUIRE). 
As the characteristics of the connection must be defined when the 
connection is established, this function serves to interrogate 
transmitted proposals, etc. 

e Rejection of a connection request (YREJLOG). 
If there are reasons for not establishing a certain connection after a 
LOGON notification, this function can be used. 

e Changing the characteristics of a connection (YCHANGE). 
This call was created in order to provide the capability of changing 


certain characteristics of a connection during the program run 
without having to cLose the connection and then open it again. 


e Deletion of a request (YCLSCON) 


e Closing of a connection (YCLSCON) 


This enables selective closing of a connection 
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35.2.3 EstabLishing a VirtuaL Connection 


A standard procedure was designed for connection setup. Depending 

on the type of computer using this procedure, different means are used to 
impLement the various procedural steps. The calls required for a DCAM 
application are shown in Figs. 3-2 to 3-7. The terminal operator procedure 
is described in Appendix A.3. 

Two steps must be taken before a connection can be established: 

e One partner must send a connection request to another. 

e The other partner must accept the request. 


The coordination of these steps is performed by the system: 


e The requests are delivered to the partner and, if others are pending, 
entered in a queue. 


Partner 1 Partner 2 


TIT incoming 


incoming requests 


Fig. 3-2 Connection request 
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e It is possible to have the arrival of a request indicated by an 
asynchronous notification (LOGON notification see 4.1.5). 


e After the notification has been issued, a contingency routine can 


estabLish which partner made the request. Following this, the request 
can be accepted or rejected (Fig. 3-3). 


Partner 1 Partner 2 


LOGON routine 


TT LOGON 
notification 


Fig. 3-3 LOGON notification; request testing and acceptance 


e The partner can interrogate this queue without having received 
a notification (see 3.2.1.3 and 4) to ascertain whether entries are 
present and can, depending on the result, issue accept calls for this 
request. (YOPNCON ACCEPT SPEC, Fig. 3-4) 


e He can also reject the request or, by not accepting it, cause the 


request to be deleted after a period of time defined in the system 
(/BCTIMES command, see “Network Management in BS2000"). 


Partner 1 Partner 2 


Fig. 3-4 Partner information inquiry and request acceptance 
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e He can also issue accept calls without inquiring. If the request 
arrives within the specified period of time, it is accepted. A number 
of this type of acceptances are entered in a queue if the requests have 
not yet arrived. They may be entered for a specific (SPEC) or an 
arbitrary (ANY) partner (Fig. 3-5). 


Partner 1 Partner 2 


Acceptance ofa 
request from a 
specific partner - 


with an entry ir 
the queuefora 
Pesci edes ud 
time (YOPNCON 
ACCEPT, ANY or 
SPEC; more than 
once if - 

necessary). 


com eu 


Fig. 3-5 Acceptance of a request 


e A further possibility is to assign partner names to a DCAM application 
when the communication access method is generated and started (see 
XSTAT macro in "Generation of a Data Communication System"). 
When the DCAM application is opened, or a /BCIN command referring to the 
processor node of the proposed partner, the named partners are proposed 
for connection setup by means of the PROCON notification. As a result 
of the notification, a request must be issued (YOPNCON ACQUIRE). The 
connection is only established if the proposed partner accepts this 
request (Fig. 3-6). 


Restriction: 


PROCON notifications are not issued to COBOL programs. 


Partner 2 


PROCON routine 


Partner 1 


Fig. 3-6  PROCON notification request to proposed partner and acceptance 
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e When generating and starting the communication access method, 
connections (XKON macro), as well as connection proposals, may be 
predefined. 


These connections are already established whenever the communication 
access method is started. However, data transmission is not possible 
until the primary task issues a call which is usually used as a 
connection request (YOPNCON ACQUIRE). 


If the partner is a terminal, it is sufficient for this to be activated 
and to be operational. 


Every communication partner that transmits a Logon call has to define the 
desired connection characteristics. When a connection request is made, the 
partner is informed of that part of the connection characteristics which 
affects him. This part consists of: 


© e The use of a data communication protocol (DEPROT); 


Restriction: 


Not supported by the system in DCAM V8.0. 


e The type of message editing used (EDIT); 
e Specification of the partner initiating data communication (PROC). 
Fig. 3-7 shows how this information is requested and defined: 


Partner 1 sends partner 2 a connection request (YOPNCON ACQUIRE), and also 
makes suggestions for EDIT and PROC to partner 2. Partner 2 can react to 
the call from partner 1 in two ways: 


e By requesting the suggestions from partner 1 (YINQUIRE) and then 
checking and either accepting or rejecting them, i.e. by sending other 
vaLues for EDIT and PROC back to partner 1 (YOPNCON ACCEPT). 


e By sending its own values for EDIT and PROC to partner 1 without 
considering the suggestions. 


C In each case the values sent by partner 2 are binding for partner 1. This 
means the values suggested by partner 1 for EDIT and PROC need not 
necessarily correspond to the current values, and therefore the user must 
inform himself of the current values after the connection is established. 


Both in the case of a request for connection setup (YOPNCON ACQUIRE) and 


the acceptance of the connection (YOPNCON ACCEPT) the partners can send 
each other connection messages. 
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If a connection was predefined, its characteristics have been defined 
during system generation. 


Partner 1 | ‘Partner 2 


Fig. 3-7 Agreement on characteristics 


3.2.1.1 Definition of the Connection to be EstabLished 


The connection to be established has to be defined in the DCAM program. 
The following information is required: 


e Name and processor name (= address) of the partner 


This information is used to address a partner when a request is issued 
or a request is accepted by a specific partner (SPEC). 

If an accept call was issued for any partner (ANY), DCAM returns the 
partner and processor names after completion of the call. 


© Accompanying information 


Here, the user defines an optional character string which, for example, 
is added to every message he receives via this connection. It may be the 
address of a data area to be assigned to this connection or the address 
of a routine which is to be activated specifically for this connection. 
This method is particularly useful for access to the common-receiver 
queue with RECEIVE ANY, but also for distribution code oriented when 
several tasks are using the same distribution code name (see also 
3.2.1.4). The content of the accompanying information is optional; 
hovever, it must not exceed 4 bytes. 


Restriction: 
Accompanying information cannot be defined in COBOL. 
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e HandLing of excess-Length messages 


Depending on the job to be done, a choice must be made between two 
possibilities; see Table 3-4 for details. 

This entry can be changed Later on during the execution of a receive 
call (see 3.3.2). 


Requirements Definitions 

- Only messages of fixed Length are The vaLue TRUNC is specified for 
expected on this connection. PROC. 

- A message that is Longer than The excess-Length portion of 
expected must be errored. The messages that are Longer than 
excess-Length part is to be expected is truncated. The 
truncated. excess-Length condition is 


indicated but the excess-Length 
part is ignored. 


- It is not possible to predict the The value KEEP is specified for 
Length of the messages arriving PROC. The excess-Length condition 
over this connection. The Length is indicated when the 1st section 
assumed to be most common is is received, and the excess- 
therefore specified and an input Length part is saved for a 
area reserved for it. further receive call. 


- The possible excess-Length is not to 
be discarded; it will be fetched 
with a further receive call after 
having been indicated. 


Table 3-4: Handling of excess-Length messages 

e Message code 
As different codes can be used on the transmission Line sections in a 
data communication system, it is Left to the user to select a code 


according to the job definition at hand; Table 3-5 provides an overview 
of the options. 


Requirements Definitions 

- The user is working with virtual The value SYSCODE is specified for 
terminals. PROC. If necessary, the messages 

- He wishes to receive messages in are converted in the data 
the code of his own host computer communication system. 


(as a rule in EBCDIC). 
- He always transmits messages in the 
code of his own host computer. 


- The user is not working with The value BINARY is used for PROC. 
virtual terminals. The messages are transmitted in 

- He wishes to receive messages in any code (transparent). 
the code used by the communication 
partner. 


- He transmits messages in the code 
which the partner can process. 


Table 3-5: Message code 
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e Data flow control 
It is possible for a connection to become overloaded, in which 
circumstances no notifications can be handled. 
By issuing a GO signal, the user can ascertain when the connection 
becomes free once more, permitting the transmission of data (SIGNAL). 


e The Logon password is specified when a connection request is to be made. 
It must be specified in the same vay as the partner (in this case a 
DCAM application) defined it during the opening procedure (see 3.1.1.1). 


e Where messages are distributed by means of distribution codes, the 
reference to the detailed description of the distribution codes must be 
specified here. This is described in detail in section 3.2.1.4 in its 
further context. / 


e The maximum Length of data (MAXLN) which is to be transmitted via this 
connection. This is a value ensuring optimum usage of the buffers 
provided by the system; it is not passed on to the communication J 
partner. 


e Message characteristics which are agreed with the partner 


As mentioned in the preceding section, the tvo partners must agree on 
some characteristics. These are also described here. 


Initiation of data transmission by one partner or the other is also 
defined. If the DCAM application is to initiate transmission, APPSTART 
is set. Othervise, there is no definition (ANYSTART). 


The type of message editing used is defined. An overviev of the 
options is provided in Fig. 3-8 (cf. also 2.3.4). 


Note: 


For connections with EDIT=SYSTEM, where ATTR-DISCO the distribution code 
is always edited in Line mode. 
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The partner is a terminal and virtual 
terminals are to be used (possibly later) 


LINE 
(Use of line terminal) 
FORM 
(Use of format terminal) 
| PHYS’) | 
| (Virtual terminals not used) 
Message editing 
with without 

Backspace character 

Function key code 

Uppercase and lowercase| NLCASE 

letters 

Hardcopy unit 


The output data is pro- 
tected by the system 


All the logical control 
characters in a message 
are interpreted and con- 
verted into device control 
characters (printer 

conversion) 


Logical acknowledgments 
are requested from the 
printer terminal 


EBIHEUEU 


The partner is an application, i.e. 
message editing is not required 


1) Message headers, if present, 2) 8103 Printer Terminals only 
are transferred in device code 3) With EDITIN = LINE only 
and the messages themselves in 4) With EDITOUT = LINE/FORM only 
EBCDIC; a message may be 5) With EDITOUT = LINE/PHYS 
C divided into submessages and 8151, 8152 or 816X devices only 
(see Table 3-7 in 3.3.1). 6) With EDITOUT = LINE only 


7) With EDITOUT = LINE and 975X or 816X devices only 
Fig. 3-8 Message editing options 
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3.2.1.2 Connection Request 


A connection request can be sent to any partner in the data 
communication system. If the partner is a terminal, the associated 
processor (e.g. a remote front-end processor) will answer the request. 
Otherwise, a response will come from the communication access method in 
BS2000 (see 3.1.1.1 and 3.1.2) or from the partner (in this case a DCAM 
application). At present, there is a choice of two possibilities for the 
processor node to which the terminal is connected: 


e If the processor node receives a request for a terminal that is not 
ready (switched off in the case of a dedicated circuit, busy in the case 
of a dial-up Line, etc.), it will reject it. 


e If the terminal is ready, it is assumed that an operator is also 


present, and the connection is established (the processor node accepts 
the request). 


The communication access method in BS2000 responds to different 

criteria. The overview in Fig. 3-9 shows that the DCAM user has several 
control options, including some in the program itself during request 
processing. A connection message can be transferred along with the request 
for checking purposes or just for isolated transmission. This message can 
have any contents and a maximum Length of 80 bytes. It is the only message 
that is transmitted vithout a connection already having been established. 


A partner wishing to issue a request has to specify the following 
information: 


e Address of the partner (partner and processor name) to which the request 
is directed. 


e Description of the connection characteristics (see 3.2.1.1). 
e Logon password, if required. 


e A connection message (optional) to be transmitted along with the 
request. 


e Type of message distribution (if distribution codes are not used), i.e. 
whether the messages transmitted via this connection are to be 
distributed using the common-receiver queue or the originator-oriented 
queue. This specification can be altered during data transmission. 


If the request vas accepted, the partner receives the following 
feedback information: 


e The accompanying information defined by the partner (see 3.2.1.1) 


èe The maximum Length of the messages to be transmitted via this 
connection (MAXLN). 


e The final definition for DEPROT, PROC, EDIT. 


e Partner characteristics (type of partner). 
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The possibility of having the statement contained in this call processed 
asynchronously is dealt with in the description of the Language features 


(see 4.1.3). 


Restriction: 


Connection messages are only delivered to DCAM applications. Terminals 
connected to TRANSDATA 960 Communication Computers cannot receive 
connection messages. 


Transmission by 
the data communica- 
tion system 


*) See section 3.2.1.1 


Fig. 3-9 Processing a request 
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3.2.1.3 Acceptance of a Request 


The basic description of acceptance is contained in the preceding sections. 
This section contains a summary of the information which can be specified 
for acceptance. The inter-relationship of the various specifications is 
shown in Fig. 3-10. 


Acceptance of the request 


from a specific partner 
(SPEC) 

Address of partner 

(name and processor name) 


from any partner 
(ANY) | 


Definition of the connection 
characteristics 
pg message 
o be passed 

otona from DCAMVER 8.0) 


only if message distribution 
is not via distribution codes 


Message distribution via common- 


receiver (CA) or originator-oriented 
(CS) queues 


synchronous processing asynchronous processing") 


T 


optionally 
Entry in a queue (Q) with maximum 
residence time (TOVAL) 
*) For further 
specifications refer 
Fig. 3-10 Acceptance of a request lo section 4.1.3. 


Once the call has been executed, the task receives the following 
information: 


e the maximum message Length on this connection (MAXLN) and 
e some partner characteristics (essential features). 

In addition, if the request accepted vas that of any partner: 
e the name of the partner 

e the name of the partner's processor 


€ the accompanying information (cf. 3.2.1.1) 
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3.2.1.4 Connection Setup - Use of Distribution Codes 


If messages are to be distributed by means of distribution codes (defined 
when the application is opened), a number of definitions must be made when 
the connection is set up. 


As already mentioned (see 3.2.1.1), the description of a connection 
contains, in this case, a reference to that section that describes the 
distribution codes. Distribution codes are described in 2 stages (see Fig. 
3-12) in order to provide maximum freedom in associating connections 

with distribution codes. 


Stage 1 Description of the code position in the message and of the 
Length of the code(s) used. The code must be contained in 
the first 256 bytes of the message and can have a maximum 
e Length of 8 bytes. 


In addition: reference to the description of the second 
stage, which may be present 8 times (COBOL) or 16 times 
(ASSEMBLER). 


Stage 2 Description of the codes used by this connection. Up to 
8 codes can be described. 

These descriptions can be shared, i.e. several connections can use the same 

stage 1 description and several stage 1 descriptions can use a stage 

2 description. 


The following must be observed: 


e The codes which are addressed by the same stage 1 description must be 
unique and 


e must all be of the same Length. 


. * If several stage 1 descriptions address a stage 2 description, the 
© Length specifications in the stage 1 descriptions must be identical. 


The possibilities that result from this method of describing distribution 
code during the setting up of a connection are as folLous: 


èe Code Length, code position in the message and the code sign are defined 
when the connection is set up and cannot be altered. 


e A partner can specify up to 64 (COBOL) or 128 (ASSEMBLER) different 
distribution codes in groups of 8. Thus, the partner can either reach 
one task via up to 8 different codes or he can read a varying number of 
tasks. 


The number varies because the assignment of codes and task via 

the distribution code name takes pLace during the execution. This 
assignment is controlled by the primary task by means of YPERMIT and 
YFORBID calls (see 3.3.5). 
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Description of 
distribution codes 


Stage 1: 
Formats 


Stage 2:") 
Values 


*) The codes of groups 1-5 and 4-8 must be unique in either case 


Fig. 3-11 Description of the formats and values of distribution codes 


3.2.1.5 Linking Up to a Predefined Connection 


A predefined connection is determined during the generation of the 
communication access method. It is established when the communication 
access method is started. However, the two partners must first connect 
themselves to the predefined connection before data transmission can begin. 


In the case of applications the primary tasks must make a connection request 
(YOPNCON ACQUIRE). In the case of a terminal this need only be activated 
and be operational. 


Because the characteristics of a predefined connection are determined 
during the generation of the communication access method, and because the 
connection is automatically estabLished when this is started, certain 
speciaL factors are involved: 


e If data is transmitted before the partner has Linked up vith the 
|» M connection negative acknowledgments are given. 


e If a partner wished to withdraw from a connection the LOSCON-ROUTINE is 
not initiated (the predefined connection remains established). 
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e A YOPNCON ACCEPT SPEC to a predefined partner can never be successfully 
terminated. If OPTCD-Q is specified, the call is entered in a queue and 
is terminated by timeout. 


The following specifications cannot be made by a YOPNCON ACQUIRE if the 
connections are predefined: 
e a connection message 


e a LOGON password 


e declarations on the data communication protocol (DEPROT) 
e message editing by the system or the user (EDIT-SYSTEM USER) 


e start data transmission (PROC=APPSTART ANYSTART). 


Pn 


Fig. 3-12 Linking up to a predefined connection 
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3.2.2 Interrogation of the Entries on Partners and Connections 


As already mentioned in the sections on connection requests and the 
acceptance of requests, it is necessary to test the entries on partners and 


connections. 
for this purpose. 


The YINQUIRE call, of which 6 variants are available, is used 
For secondary tasks, only the CIDXLATE, NAMXLATE and 


PTNCHAR variants are applicable. | 


Restriction: 


In COBOL only 3 variants of the YINQUIRE call are available. 


Table 3-6 shows the YINQUIRE variants and the programming Languages in which 


each can be used. 


Inquiry 


- Which partner is 
requesting connection? 
What are the proposed 
characteristics of the 
connection? 

- What connection message 
is to be transmitted and 
what is its Length? 


- Which partner is next in 
the queue of those 
requesting connection? 

- What are the proposed 
characteristics of the 
connection? 

- What connection message 
is to be transmitted 
and what is its Length? 


- What characteristic 
feature does the partner 
have? 


=- How many partners have 

| sent a request? 

- With hov many partners 
has a connection been 
established? 


- What is the identifier of 
the connection of which 
the partner and the 


processor names are known? 


- What are the partner and 
processor names of 
a connection whose 
identifier is known? 


Table 3-6: 


Inquiry variants 


YINQUIRE variant Programming Language 


Inquiry after an ASSEMBLER 
asynchronous LOGON 
notification 

(REQLOGON) 


Inquiry prior to 
acceptance of a 
request (TOPLOGON) 


ASSEMBLER /COBOL 


Inquiry for partner 
characteristics 
(PTNCHAR) 


ASSEMBLER /COBOL 


Inquiry for number of 
partners 
( COUNTPTN) 


ASSEMBLER /COBOL 


Inquiry for identifier ASSEMBLER 


CID (NAMXLATE) 


Inquiry for the partner 
and processor names 
(CIDXLATE) 


ASSEMBLER 
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3.2.3 Rejection of a Connection Request 


As described above (see 3.2 and Fig. 3-9), it is possible to receive 

a connection request via the asynchronous LOGON notification (see 4.1.5). 
It vas also mentioned that information on the partner that sent the request 
can be obtained together with a connection message that may also have been 
transmitted (see 3.2 and 3.2.2). After all this has taken place and 
following a check on this information it is possible to decide not to set 
up a connection with the requesting partner and to reject the request. 

The YREJLOG call is provided for this purpose. 


Only the address of the partner (partner and processor names) obtained vith 
the YINQUIRE call need to be specified. 


3.2.4 Changing the Characteristics of a Connection 

The user can change some of the connection characteristics defined during 

connection establishment. 

Only those characteristics can be changed which exclusively affect the 

partner making the changes, i.e. not those which have been agreed with 

the communication partner. 

In the YCHANGE call, all of the values Listed in the following must be set 

regardless of whether they are changed (new) values or the previously set 

(old) values. 

The following can be changed: 

e Accompanying information 

e HandLing of excess-Length messages 

e Code of the messages 

e Values for EDITIN (Input message editing) 

e Values for EDITOUT (Output message editing) 

e If required, address of the distribution code description for changing 
distribution codes described in groups (the Length and the position in 


the message and the code sign cannot be changed). 


For further information on these values see 3.2.1.1. 
(Definition of the connection to be established). 
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3.2.5 DeLetion of a Request 

A connection request sent to a partner can be deleted with the YCLSCON 
call. 

The connection request is revoked if the connection is not yet established. 
If already established it is cleared down. 


3.2.6 Closing a Connection 


Explicit closing of a connection is possible with the YCLSCON catt. 

There is no obligation to do this, as all connections are implicitly 
closed when the DCAM application is closed. Uncollected messages are 
destroyed when the connection is closed. Therefore it is recommended that 
the final message be saved with a transport acknowledgment. 

Explicit closing may be required for: 


e time-Limiting a connection 


e regulation of data throughput (connections can be closed down in order 
to give other connections better throughput rates) 


e freeing a terminal for another connection, etc. 
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3-3 DATA TRANSMISSION FUNCTION 


The requirements for data transmission are fulfilled when a DCAM 
application has been opened and a connection established. 


The data transmission function performs the following operations: 


e Transmitting a message (YSEND) 
The message to be transmitted to a communication partner is transferred 
to the data area of the communication access system. 

© e Receiving a message (YRECEIVE) 

The message from a communication partner (any one, a specific one or 
one with a specific distribution code) is entered in the data area of 
the user program. | 

e Combined transmitting and receiving (YSENDREC) 

e The data for a message is entered in the data area of the communication 
access method by means of a call, and the data of a message from the 


same communication partner is entered in the partner's own data area. 
This provides an effective means of interactive processing. 


e Deletion of receive calls and changing the CS/CA state of 
a connection (YRESET) 
With this call a process can delete either all its waiting YRECEIVE 


calls from a specified application or a specified connection, and it 
can alter the CS/CA state. 


The following facilities are available to control distribution by 
means of distribution codes: 


e Assignment of distribution code names to distribution code groups 
CYPERMIT) 


The primary task assigns specific distribution codes to the distribution 
code name of one or more secondary tasks. 


e Cancellation of this assignment (YFORBID) 


An assignment is canceled by the primary task. 
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3.3.1 Transmission of a Message 
A message transmission call, which can be issued by any task of an 
application, results in the following action: 


.@ The data to be sent to a partner in the form of a message is transferred 
to the data area of the communication access method. 


e The access method is assigned the job of transmitting the data to the 
partner. 


e The call is terminated and the access method starts transmission. 
The access method receives a number of user specifications aLong vith 
the message to be transmitted. They are suppLemented by specifications 


defined when the virtual connection vas set up (see 3.2.1.1). 


Additional specifications required under particular conditions are Listed 
in Table 3-7. 
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Requirements 


After Logon, the system announced 
the maximum Length on this 
connection. 


Acknowledgment reception was enabled 
when the application was opened 

(for the primary task=PRIMTASK or 
for the requesting task=REQTASK). 
Transport acknowledgments are to be 
processed. 

The YSEND call is to be immediately 
followed by a YCLSCON or YCLOSE call 
which means the connection may be 
closed before the data has been 
transmitted. The transport 
acknowledgment should always be 
waited for in this case. 


Messages arriving on this connection 
are to be received via the 
originator-oriented queue as of now. 


Messages arriving on this connection 


are to be received via the common- 
receiver queue as of now. 


Message editing vas not provided for 

by the system on this connection. 

The following vas set: 

- EDIT-USER: The user edits the 
messages in such a fashion that the 
communication partner can process 
them. 

- EDIT-SYSTEM and EDITOUT=PHYS: The 


system performs blocking for devices 
Everything 
else is provided by the user in such 


. with a small input buffer. 


a way that the partner can process 
it. 


Message editing is provided by the 
system on this connection. 


A special situation has arisen 

(e.g. backlog on the connection), 
which was notified by the feedback 
information for a rejected YSEND. The 
partner is to be requested to issue 
receive calls immediately. 


Upon opening of the connection PROC= 
SIGNAL was used to request the GO 


signal in the event of the connection 
being overloaded. 


Table 3-7: 
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Definitions 


The Length of the message to be 
transmitted is specified within 
the maximum Length Limits. 


A sequence number is specified so 
that the transport acknowledgment 
can be assigned to the correct 
message (maximum value=2047) when 
it arrives. 

A positive acknowledgment is 
requested (negative 
acknowledgments are generated 
automatically if the message 
cannot be delivered). 


The originator-oriented queue is 
set (CS state of the connection). 


The common-receiver queue is set 
(CA state of the connection). 


The message can be cLassified as 
follows: 

= ELEMENT: 

- SUBGROUP: 

^ GROUP; 

This identification of the message 
is transferred by the network to 
the receiver, which receives it 
aLong vith the message. If the 
receiver is a terminal, an element 
is transmitted as a submessage, 
while a subgroup or a group is 
transmitted as a message followed 
by transmission termination. 


Special rules apply to the use of 
virtual terminals (see 2.3.4, 
3.2.1.1 and Fig. 3-8). 


The message is declared as an 
express message, which means that 
its Length may not exceed 8 bytes. 


For each YSEND call a valid event 
identifier (EID) should be 
specified, via which a GO signal 
can be issued if necessary. 


Definitions for the transmission of a message 


The message Layout has to be varied in accordance vith the message 
editing option seLected: 


1st logical line 


When a Line terminal is used, the user can subdivide the messages 

into Logical Lines. Each Line is terminated with the "new Line" 
character, hex 15. The text following the NL character is automatically 
placed at the beginning of the next Line by the terminal. If the Logical 
Line Length exceeds the Line Length of the data terminal, the Logical 
Line is subdivided automatically. The beginning of a message is 
automatically placed at the beginning of a Line. Fig. 3-13 illustrates 
this by means of an example. 


2nd logical line ... 8rd logical line (2^ ceo. 


Display on e. g. a 54-character screen 


Fig. 3-13 Message to a Line terminal 


Additional functions available are: 


Function Control Character Effect 

- New Page hexadecimal OC Page throw 

= Mark-in | | hexadecimal 1D Output flashing or italicized 

- Mark-out hexadecimal 1F Output normal 

- Shift-out hexadecimal OE Shift to second character set 

- Shift-in hexadecimal OF Shift to standard character set 
e When a format terminal is used, the user transfers the message in 


the vay he receives it from the mapping routine, but vithout the 
preceding record Length field. The record Length must be transferred 
from the record Length field to the corresponding DCAM field. 
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e If the values EDIT=SYSTEM and EDITOUT=PHYS have been set for 
the connection, each message must be preceded by a header Length byte. 
The binary number contained in this byte specifies of the following 
message header (inclusive of the Length byte). The message header is 
transferred to the terminal without code conversion in contrast to the 
message proper, so that the user can use the device description during 
generation and analysis of the message header. For devices which do not 
process message headers, the message must nonetheless be preceded by 
a header Length byte, and the Length must be set to 1. 


Figure 3-14 illustrates how messages are to be formatted. 


C Length in HL 


m u nn ia N Sey 


Message length 


HL = Header length byte; contains length of HL + MH in binary 


MH = Message header; length varies depending on the device function; in 
device code. Not required for devices controlled in other ways. 


Fige 3-14 Message Layout for EDITOUT=PHYS 
The message can also be subdivided into submessages in this case and also 


when EDIT=USER has been set (see Fig. 3-15). Each submessage must be 
appropriately marked. 


Fig. 3-15 Example of message structuring 


Depending on the device type and status, different device responses have to 
be reckoned with (see "Terminal Access Support"). 


Note: 


Shared physical Lines (concentrator) are released each time a submessage 
e transmitted. 
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3.3.2 Receiving a Message or Transport AcknowLedgment 


Reception of a message means that the message from a partner is entered 
in the data area of the receiving partner's program after having been 
removed from the queue. 


This procedure is completed when the call is terminated provided that the 


call was executed synchronously. 


If the call was executed asynchronously, 


its completion merely means the communication access system has been 
assigned the job of transferring the message when it arrives. An agreed 
event identifier enables the user to receive a signal when the message has 


been transferred. 


message (see also 4.1.3). 


The user can check for this signal and then process the 


This method allows any delays arising from waiting for a message to be used 


for other processing operations. 


Which messages a task can receive depends 


on the type of application, the message distribution method used and the 
type of queue selected, and also on whether the message in question is a 
normal or express message (see Table 3-8). 


1) If the distribution code has not yet been provided 


Distributed to the 
task authorized to 


receive it according 


to distribution 
code 


Distributed to 

the first task to 
access the common- 
receiver queue 
(ANY) 


1) 


Distributed to the 
primary task 


Distributed to the 
primary task 


Distributed to the task that set 
the originator-oriented queue 
(caused the CS state) 


for or has not been assigned to any secondary task, 
the message is distributed to the primary task. 


Table 3-8: 


Message distribution and receiving 
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When issuing the YRECEIVE call, the user specifies further information 
beyond the connection description defined vith YOPNCON (see 3.2.1.1). 


e With respect to the mess&ge: 


he defines the address of the field in which the message is to be 
entered, along with the Length of this field; 

he can change the handLing of excess-Length messages defined during 
connection establishment to match this message; i.e. he can redefine 
whether the excess portion of a message is to be kept so that it can 
be fetched Later or vhether it is to be discarded. 


e With respect to caLL execution: 


interrelated information must be specified here, as illustrated in Fig. 
3-16. 


n Reception of a message 1) 


The common-receiver queue (CA) or 
originator-oriented (CS) queue is set 
for subsequent message distribution 


x) 


er om ems aiia batt Temm 


1) Only possible for message distribution without distribution codes 
2) Setting of CS for this purpose not necessary in the case of message 
distribution with distribution codes 
3) The call may be transmitted prior to connection setup. 
However, it is not executed until at least one connection has 
been established. 
4) For further specifications, see section 4.1.3. 
5) Optional: if not ified, the call is terminated immediately 
even if it cannot be executed. 


Fig. 3-16 Specifications for receiving a message 


U1788-J-275-1-7600 3-33 


After the message has been received in the specified area, further 
information is fed back by DCAM: 


e Originator specification, 


if the message vas received from any partner (ANY). 


e Sequence number of message 


as specified by the partner or generated by the system (if a terminal 
was the originator). 


e Accompanying user information 


as defined by the user when the connection was established (message 
received from any partner: ANY). 


e Structure of the message (entries in the feedback field), i.e. 


whether an element, or the Last element of a subgroup or a group (see 
Fig. 3-15) vas received. 


e Type of message (entries in feedback field), i.e. whether a normal or 
express message vas received. 


e Length of message or, if the message is Longer than the storage area 
provided, the Length of the excess portion not yet transferred (KEEP). 
If the excess-Length part is to be fetched with another receive call, 
the originator-oriented queue must have been selected previously. 


Whether or not transport acknowLedgments can be received depends on the 
definitions made when the application vas opened and on the information 
specified when the message which is to be acknowledged is transmitted 
(see Table 3-9). 
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A positive A positive acknow- 
acknowLedgment is Ledgment is not 
requested (TACK) requested (NTACK) 


The requesting task Transfer of positive Transfer of 
is to receive and negative negative 
acknovLedgments acknovLedgments to acknovLedgments 
(REQTASK) the requesting task only to the 

| primary task 


No acknowledgments 
are to be passed Neither positive nor negative 
(NOTACK) acknowLedgments are passed 


TabLe 3-9: Distribution of transport acknowledgments 


UnLess the use of asynchronous notifications vas agreed (see 4.1.5), 
transport acknowledgments are received with the YRECEIVE call. ALL 
information on the type of acknowledgment etc. is provided in the feedback 
field of the call. The field 'TACKNO' also contains the sequence number of 
the message as defined during transmission. It is thus possible to identify 
the message. 


It should be noted that the reception of a transport acknowledgment with 
YRECEIVE has no effect on the setting of the queue (CS/CA) even if this was 
specified in the call. 


Restriction: 


Where EDIT=SYSTEM, a second negative transport acknowLedgqment can be 
received when YSEND is specified. (This restriction applies through to 
DCAM V8.0). ; 
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3.3.3 Combined Transmitting and Receiving 


The information given on the two separate calls also applies to the 
combined call. As the combination only permits access to the originator- 
oriented queue, the originator-oriented queue must have been set for this 
connection (=connection status CS) with YOPNCON or a previous YSEND or 


YRECEIVE. 
Restriction: 


The YSENDREC call is not available with COBOL. 
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3.3.4 Cancelling of Receive Macros and Changing the Connection State CS/CA 


With this call asynchronous YRECEIVE macros can be canceled. 


A YRESETCANY) call cancels all ARECEIVE macros from any partner. 


A YRESETC(SPEC) call cancels YRECEIVE calls from a specified partner. 


For applications with ATTR=NSHARE or (SHARE, NDISCQ) a YRESET(SPEC) 


resets the connection state CS/CA at the same time. 
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3.3.5 ControL of Distribution Code Assignment 


The primary task controls distribution code is assignment by assigning 

a distribution code group to a distribution name or by deLeting such an 
assignment. This is one of three necessary measures which may be taken in 
any order: 


When setting up connections, the primary task defines the distribution code 
group for one or more connections (see 3.2.1.4). 


The distribution code name is entered by one or more tasks when opening the 
application (see 3.1.1.3 and 3.1.1.5). 


In this vay the primary task assigns the distribution code name of one or 
more tasks to the distribution codes of one or more connections. 


If the primary task deletes such an assignment, it inhibits data transfer 
from the connections concerned to the task concerned. 


DCAM application 
Assignment 
performed by: 


DIST # 0 


Pos. = 20 
Length = 5 


Pos.=5 Pos.=6 
Length = 1 Length we 1 


Virtual connections 


— __ — Default (no assignment) 


Fig. 3-17 Summary of message distribution with distribution codes (example) 
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3.3.5.1 Assignment of a Distribution Code Name to Distribution Code Groups 


The YPERMIT call assigns a distribution code name to a distribution code 
group. Once this assignment has been made, tasks that have defined this 
name can receive messages vith the codes of the assigned group. 


The following applies: 


e A Group of distribution codes (stage 2 definition) can be assigned to 
only one distribution code name. 


e Up to 8 tasks can use the same distribution code name. This becomes 
necessary when a single program controls several tasks (SHARED CODE, 
see 4.1.6 and 4.2.4). Tasks with identical distribution code names are 
served in accordance with the FIFO principle (FIFO-first in - first out: 
the first entry in the queue will be the first one processed; see also 
Fig. 3-18). 


d Depending on the assignment made, a task can also access the messages 
in an originator-oriented way (YRECEIVE SPEC). It is not necessary 
to select this queue beforehand (there is no CS/CA state of the 
connection when distribution codes are used). 


Up to 16 (ASSEMBLER) or 
8 (COBOL) queues - one 
per code group 


Communication 
partner A (DCAM 
application or 

terminal) 


up to 8/16 
code groups 


*) The queues (code groups) are assigned to the **) Up to 8 tasks per distribution code name 
distribution code names with separate data 
communication function calls. 


Fig. 3-18 Example of task group addressing with distribution codes 


Messages with distribution codes that vere not assigned to a distribution 
code name or that cannot be interpreted are directed to the primary task. 


Old assignments can be replaced by new ones when a new YPERMIT call is 
issued. 
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3.3.5.2 CanceLLation of the Assignment 


If a nev assignment is not to be made for a distribution code name but 
the existing assignment is to be canceled, the YFORBID call can be used. 


Data which has already been received is then transferred to the primary 
task. 
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3.4 NAME ASSIGNMENT FUNCTION 


This function permits parameters for the DCAM application or the virtual 
connection to be specified at run-time only. This is achieved by Linking 
the current values with those specified in the program in a task-oriented 
table (CLT=communication Link table). (By comparison, the entries in the 
FCB (file control block) of a program are updated using the TFT (task file 
table) whose entries were generated by the FILE macro or the /FILE 
command. ) 


Fig. 3-19 shows an example (for ACB control block see 4.1.1; for A 
structure see 4.2.1). 


Command mode: 
/APPLICATION APPLIC 4, LINK = CHAIN 4 


/EXEC* ee ee 
Program mode: 


YOPEN 


e [T] eeeee0 


The opening of the 
DCAM application 
begins with the transfer 
of the current values 
from the CLT and ACB 
control block or the A 
structure: 


Fig. 3-19 Example of assignment of a DCAM application name 
The table is set up: 
e in the progam mode (ASSEMBLER only) by means of the 
YAPPL macro for entries on the application, and the 
YCONN macro for entries on the connection 
e in the command mode (ASSEMBLER/COBOL) by means of the 
/APPLICATION command for entries on the application and the 


/CONNECTION command for entries on the connection (see "ControL 
System Command Language"). 
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The Linkage is estabLished by specifying a Link name both in the 
program and in the CLT. The following values can be updated in this fashion: 
e For a DCAM appLication: 

- the name of the DCAM application; 

- the distribution code name; 


- the password for the connection of a secondary task to an application, 
as specified in the primary task | 


- the password for the connection of a secondary task to an application, 
as specified in the secondary task; 


- the password for establishing a connection, as defined in the 
C primary task; 


e For the virtuaL connection: 
- the name of the partner; 


- the name of the processor node to which the partner is connected as 
a station; 


- the accompanying information; 


- the password for connection establishment, as specified by the 
requesting task. : 


When the YOPEN or YOPNCON call is executed, the specifications are entered 
in DCAM control blocks or data structures. They are updated with the values 
in the CLT providing it contains entries. If it does not, the original 
vaLues remain unchanged. FoLLoving this, dynamic name assignment for this 
application or virtual connection is possible again only after it has been 
closed (except for alterations of the accompanying information by means of 
YCHANGE (see 3.2.4). 


© If CLT entries are to be deleted, the YAPPL or YCONN macro or the 
corresponding commands with just the Link name should be issued. 


C : 
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4 CODING AND EXECUTION OF DCAM PROGRAMS 


This chapter does not contain exact coding instructions since separate 
manuals are provided for this purpose (see "DCAM Macros" and "DCAM COBOL 
Calls"). 


Instead it describes the specific Language-related characteristics of the 
DCAM interface. The DCAM programmer can use two Languages: 


e ASSEMBLER 
e COBOL 


After the use of DCAM in these Languages has been outlined, the following 
questions will be answered: 


e How is a DCAM program started? 


e How is a DCAM program terminated? 


4.1 WRITING AN ASSEMBLER PROGRAM 


The ASSEMBLER program interface provides the full range of DCAM functions 
as described in detail in chapter 3. 


The purpose of this section is to provide an overview of the specific 
interface characteristics. 


6.1.1 Macro CaLLs and ControL BLocks 


ALL DCAM functions are activated by macro calls. The action macros always 
refer to control blocks, in which all the parameters are stored. A distinction 
is made between two groups of calls depending on the type of control bLock 
they refer to: 

e macro calls that refer to an ACB (application control block), and 

e macro calls that refer to an RPB (request parameter block). 


The following calls refer to an ACB, which contains all the information 
on the DCAM application: 


- YOPEN (Open a DCAM application) 


- YCLOSE (Close a DCAM application). 
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If asynchronous DCAM notifications are to be processed, an ENB Cevent 
notification block) is required in addition. The identifiers for the 
contingency routine are stored in this bLock (see 4.1.5). 


Fig. 4-1 provides an overview. 


Fig. 4-1 ACB-related macro calls 


The following calls refer to an RPB containing the current parameter 
values of the action calls: 


- YSETLOG (Change the state of a DCAM application) 


- YINQUIRE (Inquire for entries about DCAM applications, partners and 
connections) 


- YOPNCON (Open a connection) 

- YCLSCON (CLose a connection) 

- YREJLOG (Reject a Logon request) 

- YCHANGE (Change the characteristics of a connection) 

- YSEND (Transmit a message) 

- YRECEIVE (Receive a message) 

- YSENDREC (Transmit a message and receive a new message) 

- YRESET (Delete receive messages and change the connection state CS/CA) 
- YPERMIT (ALLow a message to be received with a distribution code) 

- YFORBID (Prevent a message being received with a distribution code). 
Further control blocks are required in addition to the RPB for various calls: 


The parameters for a connection are Located in the CCB (connection controL 
bLock), 


the position and Length of the distribution code, the code sign and the 
references to assigned distribution code groups are Located in the 
DIP (distribution parameter block), 


and the distribution codes themselves are described and the 


DCG (distribution code group block). 
Fige 4-2 provides an overview. 
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Note: 


DCAM users connected to a packet Switching network (e.g. Datex-P) via an 
an X.25 interface must note that certain restrictions apply to calls 


reLating to connections or data transmission. They are described in the 
manual “DCAM Macros" (Appendix A.11). 


Fig. 4-2 RPB-related macro calls CL Pe L a L 


The programmer need not know the internal structure of the control blocks 
as macro calls are available to him for the generation and handling of 
control blocks. 


The following macro calls are provided for static control block 
generation: 


- YACB (Generate ACB) - YCCB (Generate CCB) 
- YENB (Generate ENB) - YDIP (Generate DIP) 
- YRPB (Generate RPB) - YDCG (Generate DCG) 


In this case the control blocks are generated during assembly. 
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Note: 


Later modifications of the bLock structure by the manufacturer may 
necessitate reassembLy. 


The control blocks can also be generated and handled by the user directly 
with macro calls 


YDDACB 
YDDCCB 
YODDCG 
YDDDIP 
YDDENB 
YDDRPB 


These macro calls describe the Layout (DSECT and CSECT) of the control 
bLocks. 


Note: 


With these macro calls source compatibility is not guaranteed, because 
the Layout of the control blocks is changed if this is required by new 


versions. 


Dynamic generation of a control block in user memory area (class 6 memory) 
or optionally in an area outside the user program (class 5 memory) during 
the program run is possible with the 


- YGENCB (Generate control block) macro. 


The program being unaffected by Later modifications, this method should 
be used. 


The following macros are provided for control block handling: 
- YMODCB (Modify the contents of control block fields), 


- YSHOHCB (Transfer the contents of identified control block 
fields to an area reserved in the program), 


- YTESTCB (Compare the control block field contents with 
specified values). 


The RPB can also be modified with any macro call that addresses it. It is 
up to the user either to create several RPB control blocks or always to 
address the same one and update its contents. 


The application characteristics described in the ACB are transferred to 
DCAM with the YOPEN call. After YOPEN execution, DCAM returns an AID 
(application identifier) in the ACB. From then on all calls referring to 
this application may use the address of the ACB control block containing 
this identifier (see Fig. 4-3). 
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*) entered by DCAM when 
the YOPEN or YOPNCON 
was executed 


Fig. 4-3 Example of control block addressing without identifiers 


It is also possible to save the AID and to enter it in the RPB used for 
further calls (Fig. 4-4). 


*) The identifier was saved after 
YOPEN or YOPNCON and entered 
in the RPB with YMODCB 


**) The identifier was entered here 
after YOPNCON or YRECEIVE ANY 
if this RPB was used 


Fige 4-4 Example of the addressing of an RPB in which valid identifiers 
were entered. 


In this case the memory area for the ACB can be used for other purposes. 
The same applies to the description of the connection in the CCB to the DIP 
and the DCG. The CID (connection identifier) returned in the CCB and 

RPB can be used after an YOPNCON, for example. YSEND and YRECEIVE or 
YSENDREC then only require RPB control blocks containing the relevant AID 
and CID identifiers. If the entry was not made by DCAM, it can be made with 
YMODCB provided the identifier was previously saved with YSHOWCB. 


The use of the identifiers is advantageous because DCAM finds all the 
information required for the call in the RPB. This speeds up processing. 
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4.1.2 Synchronous Execution of DCAM Calls 


If a call is sent to DCAM with an operand stating that it is to be executed 
synchronously, control can only be returned to the program by task 
management after this call has been processed by DCAM. This ,does not 
present any problems when DCAM is able to process the call immediately. 
However, with some functions, delays may occur due to DCAM having to wait 
for a response from the communication partner. When a virtual connection is 
being set up (YOPNCON), the communication partner must contribute to this 
operation and when messages are to be received (YRECEIVE), the partner must 
have sent them and they must be available in the data area of the | 
communication system and have peen: entered in a queue. 


The programmer can decide whether and how Long he is prepared to wait until 

the call can be executed. He defines the maximum waiting time for each call. 

He can also specify that he is not willing to wait. In this case the call 

is terminated immediately even if the instruction cannot be performed. The 

call must then be repeated Later in the program if required (cf. Fig. 4-5). 
User task System 


Waiting time 


o 
o 
000000000000 


Further processing 


Waiting time 


| Message 


Further processing 


must be fetched 
with another 
YRECEIVE 


Time 
Fig. 4-5 Example of synchronous execution of the YRECEIVE call 
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4.1.3 Asynchronous Execution of DCAM Calls 


As mentioned in the preceding section, connection establishment and message 
reception may Lead to delays. In order to increase data throughput, 
particularly if a very Large number of partners are to be serviced, these 
deLays can be used for other processing. For this purpose, the user can 
define an event (ENAEI macro) and specify its identifier EID in the 
YOPNCON, YRECEIVE or YSENDREC macro uhose instruction is to be executed 
asynchronously. Control is then returned to him immediately after macro 
termination and instruction acceptance by DCAM. The event may be, for 
example, message transfer. The user can test for this event at that 
Location in the program (SOLSIG macro) at which he wishes to process the 
message, for instance (see Fig. 4-6). 


User task System 


© Example 1 | 


ENAEI: Define event 


Transfer of event identifier 


P1 
eventing 


Further processing 


The waiting time preceding the 
arrival of the message is used 
for further processing 


Processing of the message 


Example 2 ENAEI: Define event 


Transfer of event identifier 


i Further processing 


T 
a 


he waiting time preceding the 
rrival of the message is used 
for further processing 


} Waiting time 


Processing of the 
message 


Time 


EID = Identifier of the event (in this case, the arrival of the message), is used as the 
reference point for message transfer and acceptance 
*) A maximum life is defined for YRECEIVE and SOLSIG in each case (not indicated here). 


Fig. 4-6 Example of asynchronous execution of the YRECEIVE call 
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At this point he can vait, if necessary, for a certain period of time, if 
for instance, the message has not yet arrived. 


He can, however, also Link the event with a contingency routine. In this 
case, the user should test for the event as soon as he has issued the 

DCAM call. He can do this any time provided he has defined the contingency 
routine and has received its identifier COID (ENACO macro). 


When the event occurs, the routine is started automatically (see Fig. 4-7). 


User task System 


Main routine 


ENAEI: Define event 
Transfer of event identifier 


ENACO: Define contingency 
routine 
Transfer of contingency identifier 


r 
i 
| 
I 
J 


Further processing 


EID = identifier of the event (in this case, the arrival of a message), is used as the 
reference point for message transfer and acceptance. 
COID = identifier of contingency routine 
*) A maximum life is defined for both YRECEIVE and SOLSIG (not indicated here) 
**) The waiting time before the arrival of the message is used for other processing 


Fig. 4-7 Example with contingency routine 


It should be noted that a maximum Lifetime has to be defined for the 
individual calls and that the Lifetimes are related. The Lifetime of the 
SOLSIG should be Longer than that of the DCAM call, since the SOLSIG might 
otherwise have to be repeated. 


Care should be taken to prevent actions in the program that assume 
completion of asynchronous processing without this actually having taken 
place (closing of the connection, for instance, while a YRECEIVE is being 
processed asynchronously). 
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Restriction: 


Up to 8 instructions of the same type can be processed asynchronously at 
a given time (see Appendix A.2). 


In order to be able to access values which were valid when the call vas 
issued or to transfer the address of the control block used, the user can 
define event information. 


This takes place when YOPNCON, YRECEIVE or YSENDREC is issued. It is 
transferred when the event has arrived, either in a defined field (no 
contingency routine) or in a register (when a contingency routine has 
been defined). 
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6.1.45 Feedback Information 


The user receives feedback information after the termination of a DCAM call. 
This information consists of a 4-byte code which is entered in a field of 
the ACB or RPB control block, the so-called FDBK field, and in register 15 
(see Table 4-1). 


FDB2: FDB3: FDB4: 
Reason for rejec-| Condition codes Indicators 
tion (error code) 


Table 4-1: Feedback information format 


The feedback information is made up of several bytes. By evaluating byte 1 
(FDB1) the user will have sufficient information to estimate roughly what 
needs to be done. The user can either evaluate byte 2 (FDB2) or make do 
with a Listing that permits Later evaluation. The job on hand will 
ultimately be the decisive factor in this matter. 


Bytes 3 and 4 (FDB 3-4) contain additional information, e.g. message format, 
transport acknowledgment or message, etc. 


The feedback information is always in the FDBK fields of the appropriate 
control blocks. 


In the case of a synchronous call, the feedback information includes 
information on the processing or rejection of the call. 


In the case of asynchronously executed calls, the feedback 

information only includes information on instruction acceptance or 
rejection. Register 15 and the FDBK field cannot yet contain any values 
relating to the execution of the instruction. The RPB control block will 
contain further information only after the instruction is executed. In this 
case, the user can Locate the RPB by transferring the address of the RPB in 
the EIDREF field. After a SOLSIG call the user receives the RPB address via 
the RPOSTAD field or register 3 (contingency). Then he can access the RPB 
and with YSHOWCB he can access the feedback information in the FDBK field. 


The feedback information from the SOLSIG call (register 15) or the 
contingency routine (register 2) informs the user whether the event which 
occurred was the expected one or whether an error or a timeout occurred, 
but information on the execution of the call by DCAM is not provided (see 
SOLSIG in the manual "BS2000 Executive Macros"). 


A number of calls (YOPNCON, see 3.2.1.2 and 3.2.1.3; YRECEIVE, see 3.2.2) 
provide further information besides the feedback information (see the 
corresponding sections (chapter 3) on the functions) but only if the 
feedback indicates no errors (i.e. FDB1-X'OO"'). 
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6.1.5 Asynchronous DCAM Notifications 


Asynchronous notifications can be issued to the task by DCAM for a number 
of events in the data communication system which may occur in asynchronous 
relationship to program processing and which may have a decisive effect on 
processing (see Table 4-2). 


onLy to the | connection 
primary task function 


existence function 


C : | connection function 


Table 4-2: Asynchronous DCAM notification 


These events are: 

LOGON: 

- A connection request has arrived. 
LOSCON: | | 


- A connection vas closed by the communication partner, the operator or 
due to an error. 


© - A connection is about to be closed (warning); (see /BCON and /BCTIMES 
commands in "Network Management in BS2000"). 


Note: 


If the LOSCON event occurs vithout a varning, the connection is aLready 


cleared down; if the user now enters the macro call YCLSCON, it will be 
rejected with a return code # 0, | 


PROCON: 
- Partners already defined at communication access system generation 


time (XSTAT macro in "Generation of a Data Communication System") were 
proposed for Logon in the YOPEN or a /BCIN operator command. 
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SECOND: 
- A secondary task vas opened or closed. 


- The distribution code of a message is assigned a distribution name which 
is not opened by any secondary task. The primary task must first issue 
YFORBID for the distribution name before it can receive the message 
proper. 


COMEND: 
- The communication access system vas terminated. 


- Termination is pending (warning) (see /BCTIMES command in "Network 
Management in BS2000"). 


- The DCAM application will be terminated shortly (warning for connected 
secondary task) (see /BCTIMES command). 


EXPR: 


- An express message has arrived. 


TACK: 
- A transport acknowledgment has arrived. 


The DCAM application can be notified of the event concerning it if this 

is specified when the application is generated/opened. As the event 
notification results in a contingency routine being executed, a contingency 
routine must be defined for a notification to be received. The ENACO 

macro can be used for this purpose (see "Executive Macros"). The returned 
identifier (COID) has to be transferred to DCAM via the ENB event control 
block (see 3.2.1). The notifications which are to be accepted and the 
contingency routine which is to be initiated have to be defined at YOPEN 
time for the duration of an application. 


Primary tasks are notified of all events, secondary tasks only of LOSCON, 
COMEND, EXPR and TACK. If a contingency routine is initiated, registers 1 
to 7 contain all the information required for the processing of the event. 
The other registers have no defined contents. Input to the base register 
contents is the user's responsibility. Access to register contents of the 
interrupted routine or of the main routine is possibLe vith the CONTXT 
macro (see "Executive Macros"). The priorities of the contingency routines 
are established when they are defined (ENACO) and can be modified with the 
LEVCO macro (see "Executive Macros"). 


DCAM expects a response to each notification. If no response occurs, this 
is interpreted as a rejection of the notification. The response does not 
have to occur within the contingency routine itself, just within a certain 
period of time defined during the generation of the communication system 
(see /BCTIMES command and Fig. 4-8). 


4-12 U1785-J-275-1-76500 


User task System 


Main routine 


ENACO: 
Define contingency 
routine 

Transfer of contin- 
gency identifier 


Time 


Further processing 


COID = Identifier of the contingency routine 


Fig. 4-8 Example of express messages being received via an asynchronous 
DCAM notification (EXPR) 


The decision during the generation/opening of the DCAM appLication not to 
accept certain notifications has the following consequences: 


e LOGON is not defined: Connection requests issued by the communication 
partners can only be processed by means of a YOPNCON call issued during 
the program run. 


e LOSCON is not defined: Notification of connection Loss can be 
obtained at the earliest from the feedback information from a call which 
refers to this connection. 


e SECOND is not defined: The primary task must use other means (PI 
eventing) to discover that a secondary task has opened the application 
and vhich distribution name it has. 


The primary task is unavare of messages assigned a distribution name 
without a connected secondary task. These messages are not received by 
any task and are deLeted after expiry of a system monitoring period. 


e PROCON is not defined: Pre-defined Logon proposals are not reported 
to the DCAM application. 


e COMEND is not defined: The fact that the DCAM application or the 
communication access method no Longer exists is indicated in the feedback 
information at the earliest when the next call is issued to DCAM. 


e EXPR is not defined: Express messages must be fetched with YRECEIVE 
in the order of the incoming messages. 


e TACK is not defined: Transport acknovLedgments must be fetched with 
YRECEIVE in the order of the incoming messages. 
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4.1.6 Reentrant ASSEMBLER Programs 


In BS2000, a program can control several tasks, i.e. the program is Loaded 
only once for this number of tasks. The results are as follows: 


e Loading times are shortened 


because the program is Loaded when it is called by the first task. When 
other tasks call it, the program is not Loaded again, but used by them 


also i.e. it is shared. 


e Dialog response times are shortened because the DCAM application, 
acting as the communication partner, has shared out the "burden" of 
incoming inquiries among several tasks. Timesharing task control is thus 
impLemented although only one program is used (see 2.3.1). 


e The system utiLization is improved because the paging rate is 
Loyer and the program is managed onLy once for several tasks in the 


main and page memories. 


This processing is only possible if such program modules, which are managed 
as 'shared code' in the system, are invariable, i.e. reentrant. Since, 
however, task-specific I/O areas etc. are usually also required, this means 
that a program must be divided into a 'read-onLy' section and a variable 


section. This procedure is supported by DCAM as follows: 


e ControL bLocks can be generated during the program run in a task- 


oriented area managed by DCAM or in a user area. 


e By means of the MF parameter the parameter List and the operation 
code (SVC) of the macro can be separated for calls generating and 


handling control blocks. 


e Register notation is used to a Large extent. 
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Table 4-3 and Fig. 4-9 show the possibilities available through reentrant 
programming and the required subdivision öf the program. 


Invariable Variable | 
(shared code) (task-oriented) 


Program section 


Invariable instruction 
code (using EX 
instruction, if necessary) 
Addressing of the variable 
section via registers 
(MF=E) 

If required, provision of 
memory for the variable 
section (Fig. 4-9, 

model B) 


Instructions 


Number constants 
Text constants 
Address definitions 
(DSECT) 

Parameter Lists 
(MF=L) 


Data and areas 


Table 4-3: Shared code program structure 
Model A Model B 
Task-specific 
section 


(variable) 


Reentrant P. 


(shared code) — 


Fig. 4-9 Models for shared code programming 
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Instruction code, 
incLuding input to 
registers for 
branch to 
invariable module 
(Fig. 4-9, model A) 


I/O areas 
Computation fields 
Save areas 
(registers) 
Parameter Lists 
(MF=L) 
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4.1.7 Use of Other System Interfaces 


There are no Limitations on a DCAM ASSEMBLER program using other system 
interfaces. Some interfaces or interface characteristics are in fact 
particularly suited to solving specific transaction mode probLems. 


For the purpose of data transfer betueen tasks and the synchronization of 
tasks the user is provided within the framework of the Executive macros 
with a "common memory" with "task serialization” and "inter-task 
communication". Event-driven processing is possible when using the P1 
eventing and contingency interface. 


File processing with the access methods of the data management system DVS 


is possible in the SHARED UPDATE with ISAM and USER PAM; i.e. access of a 
task group to a file is supported with the necessary protection mechanisms. 
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4.2 GENERATION OF A COBOL PROGRAM 


A series of access modules to DCAM functions was provided for use in COBOL 
programs, which permit synchronous processing. COBOL programs can control 
primary tasks in simple user problems, but are also suited to controlling 
secondary tasks especially in more compLicated problems (see also 2.3). 


4.2.1 COBOL Calls and Data Structures 


ALL calls to DCAM are formulated as branches to subroutines (CALL...); the 
associated data structures with the parameters and data fields must be 
declared in the WORKING-STORAGE SECTION. 

Six different data structures are provided for: 


e Application structure (A-Struktur): 


Description of the DCAM application; must be present at Least once in 
the program. 


e Connection structure (V-Struktur): 
Description of the virtual connection; either for each connection or 
just once for several connections. 


e Instruction structure (B-Struktur): 


Description of an instruction; either for each instruction separately 
or just once for several instructions. 


e Distribution structure (VTLG-Struktur): 


Description of message distribution with distribution codes; only 
necessary if message reception is to be controlled in this vay. 


e Wait structure (H-Struktur): 


Description of the operands causing the system to vait for the 
termination of asynchronous CALLS. 


e Data structure (FHS-Struktur): 
This is only necessary if the data are to be formatted with the 
integrated FHS C interface. (This requires the softvare product FHS 
from Version 3.0 onwards). The FHS modules must be available on the 
user TASKLIB. 


COPY elements are available for all data structures: 


YDDCUAPL for the A structure 
YDDCUCON for the V structure 
YDDCUCOM for the B structure 
YDDCUDIS for the VTLG structure 
YDDCUHAI for the vait structure 
FHSMAINP for the FHS parameters 
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Table 4-4 shows which data structures are used in the calls of the 


individual subroutines. 


acceptance and transfer is required. 


For some calls an additional area for data 


Some calls require still further areas which are not shown here (refer to 
"DCAM COBOL Catus"). 


Subroutine 


YOPEN 
YCLOSE 
YSETLOG 


YOPNCON 
YCLSCON 
YCHANGE 
YREJLOG 


YSEND 


YRECEIVE 
YPERMIT *) 
YFORBID *) 
YRESET 


*) only callable with primary task 


Table 4-4: 


Subroutines and data structures 


| FHS 
parameter 
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The subroutines perform the following functions: 


YOPEN: Opens a DCAM application 

YCLOSE: Closes a DCAM application 

YSETLOG: Changes the state of a DCAM application 

YOPNCON: Sets up a virtual connection 

YCLSCON: Closes a virtual connection 

YCHANGE: Changes the characteristics of a connection 

YSEND: Transmits a message 

YRECEIVE: Receives a message or transport acknowLedgment 
- YPERMIT: Allows data to be received via distribution code 

YFORBID: Prevents data being received via distribution code 

YREJLOG: Rejects a connection setup request 

YRESET: Resets pending YRECEIVE calls 

YMAIT: Waits for some DCAM event | 


A special convention applies to status check when this concerns the 
existence or connection function. YINQUIRE is used to call for system 
testing. The following inquiries can be made: 


- Which partner wishes to Log on next (with connection message possibly 
received in LGMSG)? (TOP) 


- How many partners vish to Log on or have Logged on? (CNT) 
- What is the state of a certain DCAM application? (APP) 
- What bndrabbq iatis does a partner have? (PTN) 
- The A and B structures are used, m an area must be specified. The Layout 


of this area varies depending on the function of the call. The function is 
defined in a special field (Table 4-5). 


Subroutine| Function 
of YINQUIRE 


YINQUIRE 


 *) Area depends on function 


Table 4-5: Status testing 
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Note: 


The subroutines may also be called using the first four Letters in a name, 
e.g. YOPN instead of YOPNCON. 


To simplify programming, it is recommended to define the data structures 
once in a source code file. The COBLUR utility routine can be used 

for the creation of a COBOL source program Library. By means of the COPY 
statement, the stored data structures can be transferred to the program 
and, if necessary, modified. Information on program compiLation is 
provided in a separate manual. 


4.2.2 Execution of the Calls 


4.2.2.1 Synchronous Execution 


In synchronous execution the next instruction after the branch to the 
subroutine is only executed once the DCAM call has been processed. For 
calls in which delays are Likely, e.g. YOPNCON: the wait for a connection 
setup request or acceptance of the connection request by the partner, or 
YRECEIVE: arrival of the message from the data communication system, a 
maximum wait period can be defined. The call is terminated after the 
specified period. If there is to be no wait, a "tentative" call is issued 
which must be repeated if necessary. 


4.2.2.2 Asynchronous Execution 


Connection setup and the reception of messages may Lead to delays (see 
4.2.2.1). In order to increase data throughput, particularly when a Large 
number of partners need to be serviced, the delays arising may be utilized 
for additional processing. The YWAIT enables the user to wait for some 
event. Once this event has occurred, he can resume processing. 

PossibLe events: 

e OPENED the YOPNCON request has terminated 

e LETTER the YRECEIVE job has terminated 

e GOSIGNAL the memory bottleneck has cleared 


e LOSCON the connection was cleared by the partner or the system 


e NOEVENT no DCAM event occurred during the wait period 
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6.2.3 Feedback Information 


After the return from a subroutine, i.e. after execution of a DCAM call, 
feedback information is stored in 3 fields of the data structure used 
(application structure or instruction structure). 

The feedback information is subdivided into 3 fields: 

- return code 


- error code 


- indicator 


The return code provides a summary of the information given in more detail 
in the error code and the indicator. It will be needed, for instance, in 
© order to branch to an error routine. 


The error code must then be saved in this routine so that it can be 
evaLuated. 


Following the execution of YRECEIVE; the indicator contains additional 
information on the type of transport acknowledgment (positive or negative) 
or the message class (element, subgroup, group; normal or express message). 


Furthermore, entries are made in 3 fields of the instruction structure 
following YRECEIVE: 


- the sequence number of the message received 


- the sequence number of the acknowLedged message (if a transport 
acknowLedgment was received) 


- the actual Length of the message received (even if the input area was 
smaller) 


Additional information is passed in the event of extra calls (YOPEN, 


YOPNCON, YWAIT) - provided the acknowledgment does not indicate any errors 
© (see the appropriate sections (chapter 3) of the functional description). 
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&.2.% Reentrant COBOL Programs 


The essential condition for the reentrant quality of a code is that the 
code was not modified in the course of execution (cf. 4.1.6). Only then can 
it be managed and used in the system as shared code. 


In employing overlay techniques, the COBOL compiler creates a root segment 
that is reentrant and various overlays that are also, subject to a few 
restrictions, reentrant. The root segment contains the V constants for 
Linking both the overlays as well as the COBOL runtime system (ITL...) 


and the CALL modules. This segment is assigned the name given in the 
PROGRAM-ID. 


The overlays are called by the root segment via PERFORM. Their names are 
made up of the first three characters of the name given in the PROGRAM-ID, 
one special character (#) and the overlay number (for instance, ABC#50). 
In these overlays, no module may be invoked with a CALL that is not 
reentrant. This is, however, true of DCAM COBOL modules. Thus DCAM calls 
may not be issued in such overlays. 


In addition, the following should be noted: 


When using the COB1 compiler, reentrant code is generated in overlay 
segments. 


When using the ANSICOB compiler, the following restrictions hold: 


- no accessing of data items defined with OCCURS ... 
DEPENDING ON eee 


- no GO TO together with ALTER allowed 
- no DISPLAY possible 


- no ACCEPT possible, 
Otherwise, reentrant code is generated. 


Fig. 4-10 illustrates segmentation in a sample COBOL program. 
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ABCDEF e.g. YSEND 
CALL Non-reentrant | 
(non-shareable) 
program components 
ABC H 01 
PERFORM 
C Reentrant 
(shareable) 
i ABC H 02 program components 


PERFORM 


Fig. 4-10 Segmentation of a COBOL program 


In order to test overlay segments for reentrancy (read-only attribute), the 
TRAITS statement must be employed when they are entered in a module Library. 
by utility routine LMR. This is necessary because the COBOL compiler does 
not explicitly test this property at the present time. 


For identification purposes, the ANSICOB compiler creates a Linkage editor 
control card (OVERLAY...) at the beginning of a module. During the LMR run 
these cards are removed vith a corresponding notification. This is 
necessary, and therefore appropriate, for further processing by the 
Dynamic Linking Loader (DLL). OnLy the Dynamic Linking Loader (DLL) is 


capable of Loading shared code and must in this case be used. It is called 
C with 
/EXEC (moduLename, Libraryname) or 


/LOAD (moduLename, Libraryname) 


Note, however, that shared modules are only Loaded into the system's class 
4 memory, where they are available to all tasks, if the system 
administrator has entered them into the appropriate system moduLe tabLes 
during initiation of the BS2000 session (cf. "System Controller's Guide" 
SHARE command). 
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Programmer: 


Module library 
"BIBLIO" 


System administrator: 


(ABC # 50, ABC # 51, ABC # 80), BIBLIO 


ABC # 50 
ABC # 51 
ABC # 80 


SHARE TABLE L 
User: | 


/LOAD (ABCDEF, BIBLIO) 
or 
/EXEC (ABCDEF, BIBLIO) 


Class 6 memory (task-specific) 


Fig. 4-11 Generation of shared code 
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4.2.5 Use of Other System Interfaces 


There are no Limitations on a DCAM COBOL program within the framework 
of COBOL use in BS2000. 


Attention is draun to the possibility of using the SHARED UPDATE mode for 
the USER, PAM and ISAM access methods of the data management System. This 
mode provides the necessary protection mechanisms for access of a task 
group to a file (see manual "DVS"). 
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4.3 EXECUTION OF A DCAM PROGRAM: DCAM TASK 


At first a DCAM task is just any BS2000 task. AS soon as a program opens a 


DCAM application within this task, the task attribute is set to "TP" 
(transaction processing). 


Batch or Task with task Batch or 
interactive task attribute "TP" interactive task 


MM M MÀ 


Task type 


Time 


Command mode 


/LOGON A /EXEC /LOGOFF 


Program mode first YOPEN last YCLOSE TERM 


Fig. 4-12 Task types 


4.3.1 Starting a DCAM Task 


Before a task can become a DCAM task, it is started as a batch or 
interactive task with the /LOGON command (see "Control System Command 
Language"). This command can be issued 


- for batch tasks on punched cards which are input Locally (by means 


of punched card readers) or remotely (by means of 8418 Remote Terminals). 


- for batch tasks from other tasks by means of ENTER files which 


contain a /LOGON command at the beginning. Batch tasks are started by 
the system if the resources are available and the Limitation defined by 


the system administator allows it. 

- for interactive tasks from any interactive terminal, e.g. an 
8161 Data Display Terminal. In this case, the task is started 
immediately. 


Note: 


The virtual connection between a terminal and an application is set up as 
early as during the predialog (see "Terminal Access Support"). In the case 
of interactive tasks, this is the connection between the terminal and the 


"SDIALOG" appLication. After such a task has become a DCAM task, the 


connection to the terminal remains in existence and it is thus not possible 
to set up a connection from this terminal to the DCAM program controlling 
the task. However, it is possible to test and modify the program from this 


terminal using IDA (see Fig. 4-13). 
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BS2000 


/LOGON 


Virtual connection and 


IDA 
commands 


Virtual connection and 
data communication with 
the interactive task in 
timesharing mode via 
the “$DIALOG” system 
application 


data communi- 
cation with 

the DCAM 
application in 
transaction mode 


Fig. 4-13 Timesharing and inquiry and transaction processing in a task 


4.3.2 Termination of a DCAM Task 


A DCAM task is returned its original task attribute when the program 

controlling it closes the Last DCAM application or is terminated. It is 

then managed as a batch or interactive task as before and is terminated 

with the /LOGOFF command. This command can be issued for 

- a batch task on a punched card in a card deck 

- as the Last command in an ENTER file 

- as input from an interactive terminal 

- in the program mode by means of the LGOFF macro or indirectly by means of 
the TERMJ macro if a branch is made to /LOGOFF. 

Tasks can also be terminated by means of 


- the operator's /CANCEL command or 


- the /CANCEL command: in the interactive task for tasks with the same user 
ID, but different TSNs, 


- the operator's /SHUTDOWN command, or 


- by abnormal task termination in the case of a system error. 
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DCAM Calls 


A APPENDIX 


A-1 DCAM CALLS 


Types of DCAM call: 


A) 
C) 


- Macro calls (ASSEMBLER 
- CALL statements (COBOL 


Type Call Function Description 
A YACB * Generates an application control 
bLock. 
A YAPPL Name Stores parameters of DCAM application 
assignment in CLT, and also deletes same. 


A YCCB Generates a connection control bLock. 


A; C YCHANGE Connection Change characteristics of a 
connection already established. 


A; C YCLOSE Existence CLoses down a DCAM application. 


A; C YCLSCON Connection Cancels a request or closes down a 
virtual connection. 

A Y CONN Name Stores connection parameters in CLT, 
assignment and also deletes same. 


* 
= 


A YDCG Generates a distribution code group 


block. 


* 


— 


A YDDACB Generates a (dummy) section for 


control block ACB 


+ 
= 


ei ee 


A YDDCCB Generates a (dummy) section for 


control bLock CCB 


* 


ni 


A YDDDCG Generates a (dummy) section for 


control block DCG 


+ 
w 


A YDDDIP Generates a (dummy) section for 


control block DIP 


* 


— 


A YDDENB Generates a (dummy) section for 


control block ENP 
A YDDRPB Generates a (dummy) section for 
control bLock RPB 


YDIP Generates a distribution parameter 


bLock. 


> 
V 
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DCAM Calls 


Type Call Function Description 


A YENB Generates an event notification block 
for relating asynchronous messages to 
contingency routines. 


| 
a 


A; C YFORBID Data Cancels the assignment of a 
communication distribution name to a distribution 


code group. 


A YSET Sets a switch, which results in 
control block macros being executed 


in PI status 


A YMODCB *) Changes items in existing control 
bLocks. 
A; C YOPEN Opens a DCAM application. 
A, C YOPNCON Sets up a virtual connection. 
A; C YPERMIT Data y Assigns a distribution name to a 
communication distribution code group. 
A} C YRECEIVE Data Receives a message, express message 
communication or transport acknowledgment. 
A; C YREJLOG Rejects a connection request. 
A YRESET Data DeLetes receive calls; 
C communication Changes the connection state CS/CA. 
A YRPB DR) ee o Generates a request parameter block. 
A} C YSEND Data Send a message or express message. 
communication 
A YSENDREC Data Combines sending a message or express 
communication message vith receiving a message, 
express message or transport 
acknowLedgment 


A; C YSETLOG Existence Changes the status of an application. 


A YSHOWCB Transfers individual items from a 


control block into the user area. 


* 


Bd 


N 
~ 


Compares an item in a control block | 
with a given value. 


As; C | YTESTCB 


YWAIT Waits for termination of asynchronous 


CALLS. 


A YGENCB Generates one or more control bLocks 


of any kind. 


A; C YINQUIRE Existence; Retrieves information on applications 


connection and virtual connections. 


*) Control block functions 
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Limit VaLues 


R.2 LIMIT VALUES 


e Asynchronous processing 


The following table shows how many asynchronous instructions may be 
processed concurrently. 


Maximum number Valid for call of type Function 
8 per application YOPNCON ACCEPT ANY Accept request from any partner 
- 8 per application YOPNCON ACCEPT SPEC Accept request from a 
specific partner. 
8 per application YOPNCON ACQUIRE Issue request 
8 per task of an YRECEIVE ANY Receive a message or transport 
application acknowLedgment from any partner 
8 per virtual YRECEIVE SPEC Receive a message or transport 
connection acknowLedgment from a specific 
partner. 


e Use of distribution codes 


The following table shows the maximum values for the definition and 
assignment of distribution codes. 


Type Upper AppLicabLe to 
Limit 
© Number of distribution code groups COBOL 
per virtual connection ASSEMBLER 


Distribution codes per code group ASSEMBLER, COBOL 


Tasks per distribution name ASSEMBLER, COBOL 


p 
oOo 


e The number of concurrently active DCAM applications which have been 
opened by the same task is Limited. The precise quantity is to be found 
in the relevant release notice for the BS2000 operating system. 


The number of "non-predefined applications" is also Limited (see manual 

"Network Management in BS2000", DCSTART command). This value can relate 

to a task or the system as a whole. These Limiting values are defined at 
the system start and can be modified during operations. 


An application can maintain only a certain number of connections 


Simultaneously. There is also a Limit to the number of connections 
a "non-predefined application" can employ (see above). 
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Limit VaLues 


Maximum message Length (MAXLND | 


Local parameter which influences the economy of the buffers provided by 
the system. It contains the maximum Length of the data being sent 


(Transport Service Data Unit, TSDU). 


USER: 
1 TSDU (YSEND) 


When EDIT 
1 message 


When EDIT SYSTEM, EDITOUT = PHYS or FORM: 
DCAM transmits the system-edited message in segments, 
is determined by MAXLN and the device capacity. It is 
ensure the device capacity is not exceeded. 


the size of which 
up to the user to 


Any records Longer than MAXLN are truncated during editing. 


Maximum Length for a user message per YSEND: 32767 bytes 


Note: 


An edited record is always Longer than user data as control characters 


are converted and protocol Labels added. 


The following table shows the maximum values of MAXLN: 


<— 65530 Default value 


4096 4096 
4096 32767 


with FEP 
MAXLN 
with DXC 


65530(*) 


(*) The results depend on the HW/SW configuration and generation. 


e Limit vaLues for resources 


The following static maximum values apply in DCAM V8.0: 


Applications in DCAM | 255 
GID/application (permitted) 32 
GID/application (not permitted) 32 
DID/application 32 


The number of applications + the number of P1 events is restricted by the 


BS2000 Name Manager to around 250 per task. 


In BS2000 the number P1 contingencies generated for a task but not yet 
executed is Limited (the maximum number in BS2000 V7.5 is 400). It may be 
possibLe to modify this value by means of a REP in BS2000 (cf. DCAM release 


notices). 


A2-2 
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Setting up a connection from a terminaL 


A-3 SETTING UP A CONNECTION FROM A TERMINAL - 


Setting up a virtual connection from a terminal is an undertaking which 
varies in accordance with the way the terminal itself was generated, with 
the options that have been preset and with the constraints imposed by the 
relevant DCAM application as the communication partner. The following 
diagrams will try to illustrate two fundamentally different approaches to 
this: 


In both cases the existence of the two communication partners is 
presupposed, i.e.: 
e the DCAM application required as the prospective partner has already 


been opened; 


Ç e the terminal has been turned on and is operational; 


e the physical connection at the Level of the transmission Line has been 
or is being set up in one of the following three ways: 


- the person attending the terminal has set it up; 


- the physical connection is a dedicated Line and requires no 
further setup; 


- the communication computer to which the terminal is connected 


sets up the Line connection in response to a YOPNCON ACQUIRE call 
from the DCAM program. 


U1786-J-275-1-7600 A3-1 


Setting up a connection from a terminaL 


Initiative Lies with the terminal (DCAM application with LOGON attribute): 


PREDIAL = NEIN Request by key input: 
PARTNAM = partnername, ETX, DU (8103, 8110, 8150, 8151) 


PARTPRO = pp/rrr, F3 (8152) 
CONPRP = NEIN DU (81 61) 


or 


PREDIAL = JA, Request via predialog: LOGON 

PARTPRO = pp/rrr PLEASE ENTER NET COMMAND notification 
O [PNCON] or entry in the 
partnername request queue 
[,OPCH = name] 
[,PW = password] 
[,MSG = message] 


C'string' 
PREDIAL — JA Fn 
] 


Or 


LIND = Km 


REJECTED, reason 
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Setting up a connection from a terminaL 


Initiative Lies with the DCAM application (opened with NLOGON attribute): 


Generation’) Terminal Communication Program | 
computer?) 


PREDIAL = NEIN, 
PARTNAM = partnername, 
PARTPRO = pprrrr, 


After YOPEN: 


PROCON notification 


CONPRP = JA, 
APLNAM = partnername 


or 


PREDIAL = NEIN, 
CONPRP = NEIN, 


Start of 


Request 
accepted 


dialog with 
DCAM application 


YOPNCON ACQUIRE 


or 


No data o quu ~ . no action taken 
munication possible 


1) see XSTAT macro in “Generation of a Data Communication System" 
?) Communication computer must have been activated with /BCIN and /BCACT commands (see "Network 


Management in BS2000") 
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GLOSSARY OF TRANSDATA TERMS 


Cross-references are underlined 


A 
Administration: 
Administrator: 


Administration center 


Administration consoLe 


Administration manager 


C 


[Communication] access 
system 


[Communication] 
application 


[Communication] 
application program 


Communication computer 


Communication partner 


[Communication] protocoL 


Computer 


Connection request 
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[TRANSDATA] Administration 


CTRANSDATA] Administrator 


Partner to the administrator. Controls 
operations by passing on jobs to the 


administration managers. 


Facility connecting the administrator 
with the administration center. 

/ 
Software module in the host and 
communication computer which executes 
jobs from the administration center 
and reports back to it. 


That set of software components of an 
operating system which offers the 
applications interfaces to the 
communication system. 


Facilities for processing data exchanged 
between communication partners. 


Processing specification for controlling 
the communication application. It uses 
the interfaces of the communication 


access system. 


Computer used to set up teleprocessing 
systems. 


LTRANSDATA-] communication partner 


Description of the conditions and formats 
relating to data transfer between similar 
functional Levels in the data 


communication system (user services, 
transport services, Link services). 


(ISO 2382) 


Request from a communication partner 
to the data communication system to 
set up a virtual connection with 


another communication partner. 


Data 


Data communication 


Data communication 
system 


Data flow control 


Data processing system 


Data sink 


Data source 


Data transmission 
network 


[DCAM] application 


[DCAM] application 
program 


[DCAM] connection 
function 


[DCAM] control block 
function 


[DCAM] data 
transmission function 


A representation of facts, concepts, or 
instructions in a formalized manner 
suitable for communication, interpretation, 
or processing by humans or automatic 


means. ISO 


Data transfer between data source and 
data sink via one or more data Links 
according to a Link protocol. ISO-E 


Complex facility comprising hardware and 
software products which enables two or 


more communication partners to transmit 
data in accordance with specific rules. 


Capacity control along the path of the 
message through the data transmission 


network. 


(ISO 2382) 


That part of a data terminal equipment 


that receives data from 
ISO-E 


a data Link. 


That part of a data terminal equipment 


that enters data into a 
ISO-E 


data Link. 


Sum total of all the hardware and software 
facilities enabling physical transfer of 
data from the data source to the 


data sink. 


Communication application which is 
controlled by at Least one DCAM 


application program and 
one or more DCAM tasks. 


User program which uses 
method and controls the 


generated during 


the DCAM access 
DCAM application. 


DCAM functions expressed by instructions 


and notifications which 


are concerned with 


establishing and clearing down 


Virtual connections. 


DCAM interface instructions for the 
generation and manipulation of controt 
blocks. ALL DCAM macro calls relate to 


these control bLocks. 


DCAM functions expressed by instructions 


and notifications which 


are concerned 


with transmitting and receiving messages 


and acknowledgments. 
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CDCAM] distribution A defined character string vithin an 

code input message enabling distribution of the 
message within a DCAM application; the 
Location in the message is optional but 
its Length is restricted. 


[DCAM] event One of a number of DCAM events used for 
coordinating certain operations in the 
data communication system. It is time- 
independent of program execution 
(asynchronous event) : 

[DCAM] existence DCAM functions expressed by instructions 

function and notifications which are concerned with 
creating and canceling DCAM applications. 


CDCAM] name assignment DCAM functions expressed by instructions 
C function or commands which allow the user to write 
the user programs vithout regard to current 


parameter values such as DCAM application 
name, partner name, etc. 


[DCAM] status function DCAM functions expressed by an 
instruction which enable a DCAM 
application to obtain information about 


itself or communication partners. 


CDCAM] task A task which has opened a DCAM 
application through an explicit DCAM 
call (primary task) or has identified 
itself to an existing DCAM application 
(secondary task). 


Dialog message Message which requires a response, or 
is itself a response. 


In the case of UTM the first message 

is the inquiry by a TRANSDATA 
communication partner. This serves either 
to start or continue a transaction. l 


- DiaLog step Part of a transaction. It begins vith 
a dialog message to a TRANSDATA 


communication partner, and ends vith the 
associated response. 


Digital data processing A data processing system which, seen as a 
system functional unit, is a sequential circuit. 
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Express message 


F 


Format terminaL 


Front-end processor 


(FEP) 


H 


Host computer 


I 


Instruction 


L 


Line terminaL 


Link services 


M 


Hessage 


N 


Node services 


Message of restricted Length to a 

DCAM application or a terminal 
transmitted with a higher priority than 
normal messages. 


Type of virtual terminal. The data 
structure is formed by fields with 
differing characteristics. 


Local communication computer which is 
connected directly to the I/O channel of 


the host computer. 


Digital data processing system whose 
primary purpose is the processing of data 
in application programs. 


An imperative statement which, in the 
context of a given programming Language, 
cannot be divided into other imperative 
statements. 


Type of virtual terminal. The data 
structure is formed by Lines. 


Services comprising node services 
and the port services which relate to 
other processor nodes. 


(ISO-2382) 


Services for handling messages to and 
from processor nodes. 
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P 


[PDN] appLication 


Port 


Port services 


© Primary task 


Processing subsystem 


Processor node 


Pragram 


Region 


Remote front-end 
processor (FEPR) 
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Communication application in the 
communication computer which uses 
the interfaces of the TRANSDATA PDN 


communication access system. 


Facility concerned with the data transfer 
between a processor node and its 
environment. 


Services provided for the transfer of 
data between a processor node and 

its environment (communication 
applications), Local peripherals, 
terminals or other processor nodes). 


Task which opens a DCAM application 
and defines its characteristics. 


Subgroup of components in the 


teLeprocessing system, consisting 

of a terminal computer and 

terminals. 

It constitutes a self-contained subsystem 
within a distributed processing network. 


Functional facility in the host computer 
or communication computer which 

provides the transport services. It 

can be addressed from throughout the 
network. 


(IS0-2382) 


Part of the data communication system 
consisting of one or more processor 
nodes which, for the purpose of 
addressing, are regarded as one by the 


transport services. 


Remote communication computer which 
is not directly connected to a host 


computer and whose function is Limited 
to data communication. 


Secondary task 


ShareabLe DCAM 
appLication 


Station 


Station services 


Y 


TeLeprocessing system 


Terminal 


Terminal user 


Terminal computer 


Transaction 


[Transaction] 
application 


[Transaction] 
application program 


Task Linking itself to an opened DCAM 
application and sharing its resources. 


DCAM application which can be used 


Simultaneously by several DCAM tasks. 


A terminating element of the data 


communication system as vieved by the 
transport services which is addressable 


from any point in the network. 


Services which simplify data 
communication by handling me messages 
transferred to and from communication 


partners. 


A system in its entirety, incLuding data 
processing and data communication 
functions. 


The set of functional units that consists 
of the data terminal equipment and the 
data circuit-terminating equipment, and 
their common interface. ISO-E 


Person who uses a terminal in order to 
exchange data with a TRANSDATA 


communication partner. 
Communication computer to which 


terminals are connected. On it are run 


communication application programs for 


terminal control and data processing. 


ProLesiihg of a self-contained job issued 
to the transaction application by 

the user. The user can be: 

- a terminal user 


- a different UTM application 
- a TRANSDATA communication partner. 


The transaction may consist of one or 
more diaLog steps. The requisite 
resources are assigned to the transaction. 


Communication partner to which 
transaction jobs are directed and 


which processes the desired transactions. 


Processing specification for the control 
of the application. It uses the program 


interface of the transaction system. 
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[Transaction] job 


[Transaction] code /TAC 
[Transaction] session 


Transaction system 


LTRANSDATA] administration 


LTRANSDATA] administrator 
CTRANSDATA] communication 
partner 


Transport acknowLedgment 


Transport services 
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Instruction directing the application to 
execute a transaction. 


Information for the control of a 
transaction. In the case of UTM the 
TAC serves to select the application 
program units. 


Period of time during which a 
communication partner can issue jobs. 
This period is delimited by the granting 
and withdrawal of certain privileges. 


Those software components which constitute 
the interface between application and 
environment. It controls and supervises 
transactions. It avails itself of the 
services of the operating system, in 
particular the communication access 

system and data base system. 


Startup, control and management of the 
TRANSDATA components of a teleprocessing 
system. 


Person or program responsibLe for the 
administration. 


Facilities which maintain virtual 
connections and exchange data. 


Notification indicating completion or 
abnormal termination of data 


Services for the exchange of data 
between communication partners. 
Initiates and monitors the movement of 
messages through the data transmission 
network and manages virtual connections. 


u 


UnsoLicited message 


User services 


CUTM] application 


CUTM] application 
program 


LUTH] [application] 
program unit 


CUTM] dialog step 


LUTMJ Linkage program 


A message vhich neither requires 

a response and nor is itself a response. 
If a terminal user sends such a message 
to an application program unit, he will 
receive a standard acknowLedgment from 
UTM. If another TRANSDATA communication 
partner sends such a message, no 
standard acknowledgment is received from 
UTM. 


Services which serve to transmit 
messages for one of the two 
communication partners. 

The user services comprise the station 
services and the port services which 


relate to the communication partner 
concerned. 


Communication partner to which 
terminal users, UTM applications 


and other TRANSDATA communication 
partners can direct transaction jobs. 

The application processes the desired 
transactions. After being generated it 
is controlled by the application program. 


Processing specification for the control of 
the UTM application. It uses the UTM 
program sinterface and consists of the 


UTM Linkage program and the user's. 
program units. 


Self-contained part of a UTM application 
program which processes a sub-probLem of 

an application. It is addressed by means of 
the transaction code. UTM activates 

the program unit when there is a message 
for it. A program unit carries out one 
diaLog step at the most. 


Part of a transaction. It commences 

with a dialog message sent by the 

terminal user or another TRANSDATA 
communication partner to an application 
and terminates vith the response from that 
application. 


UTM application program unit prepared 
by the system. ALL that the user does is 


define its scope. This program serves to 
connect the application program to the UTM. 
Every application program includes such 

a Linkage program. 
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[UTM] terminal 


LUTH] transaction 


CUTM] [transaction] job 


LUTM] [transaction] 
session 


Md 


© Virtual connection 


Virtual terminal 
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Conceptual terminal which exists in 

name only. It is defined at the generation 
of the UTM application and decouples 

the Latter from the data communication 
networke A UTM terminal can stand for 
several physical terminals and a number of 
UTM terminals can stand for just one 
physical terminal. A UTM terminal can also 
stand for any TRANSDATA communication 
partner. The allocation may be altered . 
during operation by means of an 
administration command. 


Processing of a self-contained job by the 
application, which for this purpose can 
use one or more program units. | 

A transaction can consist of one or 

more dialog steps. Resources, such as 
storage space etc., are allocated to it. 


Instruction directing a UTM 
appLication to execute a transaction. 
It incLudes a transaction code and, if 
appLicabLe, the data to be processed. 
It is submitted by the terminal user, | 


by UTM program units of the same or 
a different application, or by other 


TRANSDATA communication partners. 


Period of time during which a terminal 
user, a different UTM appLication or 

a TRANSDATA communication partner can 
submit certain jobs to a UTM 
application. It commences when the 
relevant authorization is given and ends 
when this authorization is withdrawn. 


Pairing of two communication partners 
which enables them to exchange data. 


Conceptual representation of a terminal 
whose functions are mapped onto the 
physical characteristics of different 
terminals. 
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